A document about what to document and how to document it for people who create things that need documentation.
Fuchsia is a new operating system. Effective documentation allows new people to join and grow the project by having all necessary documentation be clear and concise.
The documentation described here is intended to address a technical audience, i.e. those who expect to implement or exercise APIs or understand the internal dynamics of the operating system. These standards are not intended for end-user product documentation.
Document protocols, introduce essential concepts, explain how everything fits together.
Documentation that is only for developers working on creating or maintaining a specific part of the code should be kept in the same directory as the source code.
Documentation that should be generally available to developers must be available in one of two locations:
/docs. In the
/docs/directory, you should create your documentation or images in one of these sub-directories:
best-practicesGeneral best practice guidelines on how to develop with Fuchsia source. If you create best practice documentation about about using a specific feature of Fuchsia, you should create the documentation in the same directory as the other documentation for that specific feature.
developmentInstructions, tutorials, and procedural documentation for developers that are working on Fuchsia. This directory includes documentation on how to get started, build, run, and test Fuchsia and software running on devices operating Fuchsia. You should organize the content that you create by specific activities, such as testing, getting started, or by workflow topic.
the-bookConcept and developer guides about the features of Fuchsia. You should organize the content that you create by specific features.
imagesImages that are used in the documentation. You should place images in this common directory and avoid placing images in the same directory as documentation.
Most documentation can be divided into four categories:
See Documentation Types for more information.
However, comments in your code are very important for maintainability and helping other people understand your code. See the Code Comment Guidelines for style guidelines related to comments for your code.
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 Documentation Style Guide.
Use absolute paths starting with ‘/’, like
/zircon/public/sysroot/BUILD.gn. Never use relative paths with “..” that point to content outside of
Documentation is only useful when users can find it. Adding links to or from existing documentation greatly improves the chances that someone can find your documentation.
Tips for leaving breadcrumbs:
The documentation on Fuchsia.dev uses the Hoedown Markdown Parser.