Documentation style guide

This document gives writing style guidance for Fuchsia.dev. These guidelines build on the general guidance in the Google Developers Style Guide.

In this guide:

Tone, voice, and grammar

When writing Fuchsia documentation, enforce the following style, tone, and grammar guidelines to ensure content is clear, consistent, and accessible.

Use plain U.S. English

Write clear, direct U.S. English using simple words and concise sentences. Use standard contractions (for example, it's, don't, you'll) to create a natural, approachable tone. Avoid idioms, regional colloquialisms, or slang that may be difficult for non-native English speakers to translate.

Address the reader in second person ("you")

Write directly to the reader in the second person ("you").

Recommended: Use second person to speak directly to the developer:

You can install Fuchsia by running the following command:

Not recommended: Avoid third-person phrasing ("users can") or first-person plural ("we can"):

Fuchsia users can install the OS, and then we can run the test.

Use present tense and active voice

State facts and system behavior in the present tense. Avoid future tense ("will"), which can introduce ambiguity about when an action occurs. In addition, use active voice over passive voice so the subject performing the action is clear.

Recommended: Active voice and present tense:

The command creates a configuration file in the working directory.

Not recommended: Passive voice and future tense:

A configuration file will be created by the command.

Spell out acronyms and use consistent terminology

Spell out acronyms and abbreviations on first mention in a document, followed by the acronym in parentheses (for example, "Looks Good To Me (LGTM)"). Ensure technical terminology matches the official Fuchsia glossary.

Outlines and navigation lists

Include top-level outline and sub-section lists

Long or multi-section documents should provide navigation lists to help readers orient themselves:

  • Include a top-level outline navigation list near the top of the document (after the introduction and before the first ## section heading).

  • Include a sub-section step list at the top of major sections (## headings) that contain multiple sub-sections (###).

Keep top-level outlines non-redundant

The top-level outline navigation list should list only major sections (## headings). Do not nest sub-section (###) links under major section items in the top-level outline if those sub-sections are already listed at the top of their respective major section. Keeping the top outline clean avoids redundancy.

Choose between numbered and bulleted navigation lists

Use numbered list items (1. [Section title](#anchor)) only when sections are meant to be executed in sequence, such as in a tutorial or how-to guide. For sequential procedures, precede the navigation list with "The steps are:".

Recommended: Top-level outline for a sequential procedure:

The steps are:

1. [Prerequisites](#prerequisites)
2. [Build Fuchsia](#build-fuchsia)
3. [Set up Device Cloud](#set-up-device-cloud)
4. [Troubleshooting](#troubleshooting)

Use bulleted list items (* [Section title](#anchor)) for non-sequential topics, such as an overview, concept page, index page, or reference document. Do not include "The steps are:" when the sections are non-sequential.

Recommended: Top-level outline for a non-sequential reference or overview document:

* [Overview](#overview)
* [Available skills](#available-skills)

For major sections containing multiple sub-sections, provide a sub-section list at the top of the section:

## Set up Device Cloud {:#set-up-device-cloud .numbered transformation="converted"}

1. [Set up environment](#set-up-environment)
2. [Check out device](#check-out-device)
3. [Recover and flash](#recover-and-flash)
4. [Serve packages](#serve-packages)

Text and links

Follow the 80 character limit

In the Fuchsia project, the maximum line length for code is 100 characters, while the maximum line length for documentation is 80 characters. Wrap all prose lines at a maximum length of 80 characters.

Notable exceptions to this rule are URLs, reference link definitions (such as [reference-id]: https://...), and top-level YAML frontmatter, which remain on a single line without wrapping.

Code tends to be indented (blank space on the left of the page), while English prose (documentation) tends to form paragraphs of text. This difference leads to different width specification.

Use {:.external} to mark any links that are not within fuchsia.dev, fuchsia.googlesource.com, or fuchsia-review.googlesource.com:

This is an [external](http://example.com){:.external} link.

Notice the external link icon: This is an external link.

In general, Fuchsia recommends using reference-style links in Markdown files. Reference style links use a reference identifier associated with the link, and then refers to that identifier whenever you use the link in the doc. This makes links easy to update in the document.

Recommended: Create an identifier where you want the link.

In this example, the link identifier is called fuchsia-home:

Welcome to the [Fuchsia home page][fuchsia-home].

And then define it at the bottom of the document:

[fuchsia-home]: https://fuchsia.dev/

Not recommended: Writing an in-line link like the following:

Welcome to the [Fuchsia home page](www.fuchsia.dev).

You can read more about reference style links in the external Markdown Guide.

Use correct links to different Fuchsia content

In the Fuchsia documentation you can link to three types of contents:

  • /docs/ - Link to documents that are in the /docs/ directory of the Fuchsia source tree. These links must link to a file with an .md extension. For example, /docs/concepts/README.md.

  • Source code - Link to source code files that exist within the Fuchsia source tree. These links can link to any file extension, but these files must exist in the source tree. For example, /sdk/lib/fdio/fdio.cc.

  • Reference documentation - Links to auto-generated Fuchsia reference documentation.

    • Most of the Fuchsia reference documentation doesn't exist in the source tree, but is published on fuchsia.dev. These links must be used as fully qualified URLs. For example, https://fuchsia.dev/reference/fidl/fuchsia.io.
    • However, some Fuchsia reference documentation exists in the source tree. These documents exist in /docs/reference/ and are published in the https://fuchsia.dev/fuchsia-src/reference/ section. These links must link to a file with an .md extension. For example, /docs/reference/fidl/bindings/overview.md.

Once you have created a valid markdown document, run doc-checker to ensure that your document uses valid links. When you try to submit a change that includes an .md file, Gerrit runs doc-checker and blocks submission if you have broken links.

To run doc-checker locally, use the fx format-code tool:

fx format-code

Headers

Use sentence case for page and section titles

All titles and section headers (#, ##, ###) must use sentence case.

Recommended: Using sentence case.

# This title is an example of sentence case

Not recommended: Using title case:

# This Title is an Example of Title Case

Use dashes, not underscores, for anchors

By default, fuchsia.dev creates anchors using underscores (_) in place of spaces. When creating a custom anchor for a section heading, use dashes (-) instead of underscores, using {#section-title} (or {:#section-title}). Also, use dashes for file names.

Recommended: Using dashes for anchors:

## This is a section header {:#this-is-a-section-header transformation="converted"}

Do not add custom anchors to page titles

The main page title (level 1 heading #) does not need a custom anchor. Custom anchors should only be applied to sub-section headings (##, ###). Remove any custom anchor (such as {#anchor-name}) from the # Title line.

Lists

Include empty lines between list items

In bulleted lists and numbered lists, include an empty line between items for readability and proper rendering on fuchsia.dev. In addition, include an empty line between a parent list item and the start of a nested sub-list.

Recommended: Add empty lines between items and before sub-lists:

* First list item.

* Second list item.

  * First nested sub-list item.

  * Second nested sub-list item.

Not recommended: Consecutive list items without empty lines:

* First list item.
* Second list item.
  * First nested sub-list item.
  * Second nested sub-list item.

Callouts (notes, warnings, and tips)

Use supported DevSite callout syntax to highlight important information on fuchsia.dev. To create a callout box, start a paragraph with one of the supported DevSite callout keywords followed by a colon (:):

  • Note: ...
  • Caution: ...
  • Warning: ...
  • Important: ...
  • Tip: ...

Keep callout boxes concise. Notes and other callouts should typically consist of a single paragraph or short sentences. Do not put bulleted or numbered lists inside a callout box.

Recommended: Use DevSite callout syntax and keep callout content concise:

Note: This is an example of a concise DevSite note callout box.

Warning: Running this command overwrites existing configuration files.

Not recommended: Do not include lists inside callouts or use unsupported alert formatting:

  • Do not put bulleted or numbered lists inside a callout box.

  • Do not use GitHub-style blockquote alerts (for example, > [!NOTE], > [!TIP], or > [!WARNING]). DevSite does not support them.

  • Do not use bolded or italicized lead-ins (for example, **Note:** or _Note:_). These render as normal body text rather than a callout box.

    **Note:** Do not use bolded lead-ins.

Horizontal rules

Do not use --- horizontal rules or separators in Markdown documents. Section headings (##, ###) provide sufficient visual separation and structure on fuchsia.dev without needing decorative horizontal lines.

Code samples

Use posix-terminal for shell command examples

Recommended: Allow readers to easily copy the content in a code block by adding posix-terminal after ``` for a shell command.


```posix-terminal
fx ota
```

This code block is rendered with $ in the front of the command:

fx ota

Not recommended: Don't hardcode a $ character in the command.

$ fx ota

Disable the copy feature

Recommended: Add none or none {:.devsite-disable-click-to-copy} after ``` for code or output log examples that should not be copied.


```none {:.devsite-disable-click-to-copy}
$ my_command
It won't be necessary to copy and paste this code block.
```

This code block is rendered without the copy icon in the top right corner:

$ my_command
It won't be necessary to copy and paste this code block.

Not recommended: Enable the copy feature for view-only content. If you don't specify anything after ```, the copy feature is enabled by default.


```
$ my_command
It won't be necessary to copy and paste this code block.
```

This code block is rendered as below:

$ my_command
It won't be necessary to copy and paste this code block.

Use paths instead of URLs when referring to source code

Recommended: Any links that refer to source code should be referred to by path only. You will get a static error check otherwise.

Update the [state header][sh]
[sh]: /zircon/system/ulib/inspect/include/lib/inspect/cpp/vmo/state.h