Style Guide

The Docs is styled according to this Style Guide.

Generally, the Style Guide follows the Google Style Guide.

This document serves the following purposes:

It briefly highlights the most important rules.
It describes the rules not covered by the Google Style Guide.
It specifies which rule to use if the Google Style Guide allows alternatives.

Layout and structure

File name

The file should be named in kebab-case (databet-users.md) to match the document title (DATA.BET users). This is necessary for the file to be easily found in the repository.

Title

Google Style Guide - Headings and titles

The title should be a top-level heading (# Title), and no other top-level headings should be used in the document. The title should be sentence-cased.

Description

If the main description of the document is brief, it should be placed right after the title without an additional heading. If it requires a separate section due to a large amount of content, name the section accordingly:

Introduction - for guides, user manuals, etc.
Overview - for technical documentation, API references, etc.
Abstract - for scientific papers, researches, etc.

Headings

The document should contain a strict hierarchy of headings. Headings should be sentence-cased. Headings should not contain links.

Lists

Google Style Guide - Lists

There are four types of lists used in the documents:

bullet list is used for unordered items.
numbered list is used for ordered items. Prefer numbers over letters.
description list is used for items that need a multi-row description. The key should be bolded. If the description starts on a new line, it should be indented.
table is used when there may be three or more pieces of related data (columns) or when neither column is a description.

Start each list item with a capital letter, unless case is an important part of the information conveyed by the list — such as in a list of glossary terms.

End each list item with a period or other appropriate sentence-ending punctuation, except in the following cases:

If the item consists of a single word, don't add end punctuation.
If the item doesn't include a verb, don't add end punctuation.
If the item is entirely in code font, don't add end punctuation.
If the item is entirely link text or a document title, don't add end punctuation.

If there is an introductory sentence, it should end with a noun, for example, "The list includes the following items:"

Links

A link to a document (page) should be named after the title of the document it leads to. However, a link may be represented as is. In any case, prefer to make links open in the same tab, leaving the choice to the reader. When making a named link open in a new tab, indicate that by appending the next icon: ⤴. For example, Google ⤴

Images

Google Style Guide - Images

Figures, charts, screenshots, etc, should be aligned left and be placed right after the text that references them.

Captions

If at least one image in the document (page) requires a caption (for example, to be referred to in the text), all images in the document should have captions and be aligned in the center. The caption should be italic and have the following form: "Figure X. Caption." (with end punctuation) where X is the number of the figure in the scope of the documents. Ensure you have blank lines before the image and after the caption. When possible, use descriptive sentences for captions. For example, prefer Figure 1. Event calendar shows booked events. over Figure 1. Event calendar. Ensure you provided alt for the image (![Alt text](../img_path.png)). When referring to an image in the text, do not capitalize the word "figure" and do not include the caption.

Notes

Use the following annotations and highlight them accordingly:

Grammar and style

Privacy and security

Do not expose security keys, passwords, or any other sensitive information in the documents, unless it is data for sandbox environments or examples.

Do not expose staff names, emails, or any other personal information. Take care to blur that on screenshots.

Negatives

Google Style Guide - Negation contractions

Either use contractions (don't, can't, etc.) or bold the word "not" in the text. This way you prevent the reader from missing the word not.

Slashes

Google Style Guide - Slashes

Avoid using slashes in the text, unless it is a code sample. Do not use slashes in dates.

Second Person

Google Style Guide - Second Person

Address the reader of your documents using the second person instead of the first person: use you or your instead of we, our, or us. Assume that the reader is the person who's doing the tasks that you're documenting. Use the word user only to refer to the user of the software that your reader is developing.

It's OK to use first-person plural pronouns (such as we, our, or us) to refer to the organization that's represented as the author of the document. However, ensure that the antecedent for the pronoun is clear.

Consistent terminology

Do not use synonyms for the same technical term. Name proper nouns in a single way throughout the docs.

Bold

Google Style Guide - Text Formatting

Use bold formatting for UI elements and at the beginning of notices.

Underline

Do not underline.

Italic

Use italics formatting when drawing attention to a specific word or phrase, such as when defining terms or using words as words.

Check list

This is the check list template for editing a document:

[ ] file name
[ ] kebab-case
[ ] matches the document title
[ ] title
[ ] top-level heading
[ ] no other top-level headings in the document
[ ] description section is named properly (if needed)
[ ] headings
[ ] hierarchy
[ ] sentence case
[ ] no links
[ ] lists
[ ] introductory sentence
[ ] capital letters
[ ] ending periods (if needed)
[ ] links
[ ] named after the title of the page
[ ] images
[ ] left-aligned or full-width
[ ] captions properly formatted
[ ] alt specified
[ ] Notes
[ ] properly formatted
[ ] Language
[ ] Negatives
[ ] Slashes
[ ] Second Person
[ ] Consistent terminology
[ ] Bold, Italic, No underscore