Documentation standards overview

This document outlines standards, structure, tone, and best practices for Fuchsia documentation.

Document locations

  • Documentation specific to developing a specific Fuchsia feature: Documentation for developers creating or maintaining a specific part of the Fuchsia codebase should be kept in the same directory as the source code. These docs are usually in the form of README.md files embedded throughout the Fuchsia codebase.

  • General documentation for Fuchsia developers: Fuchsia documentation should be created in /HEAD/docs/. In the /docs/ directory, you should create documentation in one of these sub-directories:

    • get-started: Specific guidance to download, set up, and start developing on Fuchsia should go in /docs/get-started. This content should contain opinionated, short tutorials that help new users get started on Fuchsia, and link to additional documentation in Fuchsia.dev.
    • development: The /docs/development/ directory (which displays on the site as "Guides") contains instructions and tutorials for developers working on Fuchsia. This directory includes documentation on how to build, run, and test Fuchsia.
    • concepts: The /docs/concepts directory contains in-depth explanations of specific features of Fuchsia and how they work, including operating system overviews, frameworks, architecture, and packages.
    • reference: The /docs/reference/ directory contains generated reference docs on Fuchsia tools and APIs, including FIDL and kernel reference.
    • contribute: The /docs/contribute/ directory contains code and documentation contribution processes and best practices, including documentation code and style guides, code polcies, and governance.
    • images The /docs/images/ directory contains images used in the documentation. You should place images in this common directory.

Document types

Most documentation can be divided into the following categories:

  • Procedural
    • Getting started - Initial setup documentation
    • Guides - Task-oriented documentation
  • Conceptual - Foundational documentation focused on teaching more about Fuchsia, Fuchsia architecture, and Fuchsia components
  • Reference - Documentation focused on detailing the syntax and parameters of Fuchsia APIs and tools. This documentation is usually auto-generated.

See Documentation Types for more information.

Documentation and code style guides

It's important to follow documentation style guidelines to ensure that the documentation created by a large number of contributors remains consistent. See the Documentation style guide for specific documentation guidance and Code sample style guide for code sample guidance.

Search best practices

Documentation is only useful when users can find it. Some findability and search best practices include the following:

  • Add your document to the table of contents: Add links to documentation in the left sided navigation on fuchsia.dev. See Site navigation and TOC files for more information.
  • Cross-link documentation: Add links to documents on subjects that help readers better understand the content of your document. For example, the conceptual document for the Fuchsia emulator links to relevant guides and getting started documents about the Fuchsia emulator.
  • Use consistent terminology: If you're writing about a specific concept in Fuchsia, verify that you are using consistent terminology. Use the glossary to verify terms.

Documentation file formats and file names

All documentation for Fuchsia is written in Markdown (.md), and Fuchsia.dev uses the Hoedown Markdown Parser.

The site's navigation is configured by _toc.yaml files, which are included in every documentation directory. Use the guidance in Site navigation and TOC files to update these files.

File and directory names should be lowercase, and separate words with hyphens, not underscores. Use only standard ASCII alphanumeric characters in file and directory names. If the file name contains a command with an underscore, then you can include the underscore.

General guidance on style and tone

  • Write in plain U.S. English. Write in clear, direct U.S. English that makes content easy to understand. Use simple words, be concise, and use contractions like it's or don't.

  • Be respectful. Follow the guidelines set forth in Respectful Code.

  • Write in second-person ("you"). Fuchsia documentation is written to the user ("you"). When For example, "You can install Fuchsia by doing the following...". Do not refer to the reader in the third person ("Fuchsia users can install Fuchsia by...") or use "We" ("We can install Fuchsia by...").

  • Write in present tense. Always document the system as it is, not as it will be. Words such as "will" are very ambiguous. For example "you will see" leads to questions like "when will I see this?" In 1 minute or in 20 minutes? In addition, do not refer to future product features unless necessary. Mentioning future plans that might not happen becomes a maintenance burden.

  • Keep sentences short and concrete. Using punctuation allows your reader to follow instructions and understand concepts. Also, short sentences are easier to translate.

  • Know your audience. Define your audience before you write a document. Knowing your audience allows you to understand what information your audience should be familiar with. When a document is meant for a more advanced audience, state that up front and let users know that as a prerequisite before reading your document.

  • Use active voice. Try to write in active voice since passive voice can make sentences ambiguous and hard to understand. Here's an example:

    • Active voice: "The operating system runs a process." In this case, the subject performs the action denoted by the verb.
    • Passive voice: "A process is being run." The subject is no longer active, but is being acted upon by the verb — it's passive. In most cases, if you use "by" this indicates that your sentence might be still be in passive voice.

  • If you use acronyms, define them the first time you write about them. For example, looks good to me (LGTM). Don't assume that everyone will understand all acronyms. You do not need to define acronyms that are industry standards such as TCP/IP.

  • Define technical terms and avoid jargon. Fuchsia documentation should be accessible to all levels of developers. Avoid overcomplicating documentation with uncommon or highly technical words. If you're using Fuchsia-specific terms, define them in the glossary. Avoid invented words.

  • Avoid colloquial phrases or regional idioms. Keep in mind that many Fuchsia users may not be native English speakers. Avoid difficult to translate idioms, like "that's the way the cookie crumbles." While it might make sense to you, it doesn't translate well into other languages.

  • Avoid referencing proprietary information. This can refer to any potential terminology or product names that may be trademarked or any internal information (API keys, machine names, etc…) internal to your company.

  • Use gender-neutral pronouns. Don't use he, him, his, she, or her, and don't use he/she or (s)he or other such punctuational approaches. Instead, use the singular they.

  • Use consistent terminology. Ensure that terms are consistent in code, UI, and documentation. Use common terms when possible, and use the glossary to verify terminology.