Google Cloud Community tutorial style guide
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:
- Create a new folder for your document.
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.Name your new document file
index.md.Store images and source code in the same folder.
(Optional) Use EmbedMd to include snippets from the source code files in the
index.mdMarkdown 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:
Make a single Markdown file at the top level of the
tutorials/folder.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.
Copy the Markdown source contents of the tutorial template file into your new Markdown file.
Replace the explanations and examples in the template with your tutorial content.
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.