This document outlines standards, structure, tone, and best practices for Fuchsia documentation.
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:
/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./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./docs/concepts directory contains in-depth explanations of specific features of Fuchsia and how they work, including operating system overviews, frameworks, architecture, and packages./docs/reference/ directory contains generated reference docs on Fuchsia tools and APIs, including FIDL and kernel reference./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.Most documentation can be divided into the following categories:
See Documentation Types for more information.
It is important to try to follow documentation style guidelines to ensure that the documentation created by a large number of contributors can flow together. See the Documentation style guide for specific documentation guidance and Code sample style guide for code sample guidance.
Documentation is only useful when users can find it. Some findability and search best practices include the following:
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.
Write in plain U.S. English. You should write in plain U.S. English and try to avoid over complicated words when you describe something. It‘s ok to 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 or and understand concepts. Also, short sentences are much 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:
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 might be considered industry standards such as TCP/IP.
Define jargon and avoid highly technical words. 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 jargon, define it in the glossary.
Avoid coloquial phrases or regional idioms Keep in mind that a lot of users are non-native English speakers interested in Fuchsia. 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.