Powered By GitBook
styleguide
Learn about style guidelines for writing Google Cloud community tutorials.
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

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.
Last modified 6mo ago