Edit on GitHub
Report issue
Page history

Google Cloud Community tutorial style guide

Author(s): @kopriva @jimtravis ,   Published: 2020-09-21

This document provides guidance for contributors to the Google Cloud Community site.

The Google Cloud Community site includes a wide range of documents that show people how to use Google Cloud in various scenarios and with various tools and resources. To make it easier for you to write documents and to make it easier for your readers to use the documents, we provide some basic guidelines that documents on this site must follow.

Much of the material in this style guide is derived from the more comprehensive Google developer documentation style guide. For general style matters—such as capitalization, tone, voice, and punctuation—see the main developer documentation style guide.

Voice, tone, and general guidance

Here are some general guidelines to keep in mind:

  • Instruct the reader. Don't sell, market, or editorialize.
  • Tell the reader at the beginning what assumptions you're making in the tutorial.
  • Don't use absolutes and superlatives (such as instantaneously, perfectly, 100%, or the best) unless you can back up what you're saying with documentation.
  • Only make performance claims that you can back up with current data.
  • Only use logos, diagram, images, and trademarks for which you have explicit permission.
  • Don't alter, truncate, or abbreviate Google Cloud product names. For example, it’s Cloud Storage, not GCS.

Visual assets

Google Cloud offers a library of logos, icons, and architectural diagram assets for your use.

File organization and naming in GitHub

How you name and organize your files in GitHub depends on whether you are submitting a single standalone tutorial file or submitting a tutorial file with a set of supporting files, such as images and source code.

Contribute supporting files with the tutorial

If you have additional image or source code files that go along with your tutorial, do the following in GitHub:

  1. Create a new folder for your document.
  2. Name the folder with key words from your title, separated by hyphens, omitting words like and and the.

    For example, if you submit a tutorial named "Using Cloud SQL to conquer the world", name your folder using-cloud-sql-conquer-world.

  3. Name your new document file index.md.

  4. Store images and source code in the same folder.

  5. (Optional) Use EmbedMd to include snippets from the source code files in the index.md Markdown file.

Contribute a single standalone tutorial file

If you don't have additional files that go along with your tutorial, do the following in GitHub:

  1. Make a single Markdown file at the top level of the tutorials/ folder.

  2. Name your new document file with key words from your title, separated by hyphens, omitting words like and and the.

    For example, if you submit a tutorial named "Using Cloud SQL to conquer the world", name your file using-cloud-sql-conquer-world.md.

Follow the tutorial template

We provide a tutorial template that explains and demonstrates each part of a tutorial document.

  1. Copy the Markdown source contents of the tutorial template file into your new Markdown file.

  2. Replace the explanations and examples in the template with your tutorial content.

Submit a tutorial

Share step-by-step guides

Submit a tutorial

Request a tutorial

Ask for community help

Submit a request

View tutorials

Search Google Cloud tutorials

View tutorials

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.