Documentation Standards

A document about what to document and how to document it for people who create things that need documentation.

Why document?

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.

Who is the audience?

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.

What should I document?

Document protocols, introduce essential concepts, explain how everything fits together.

• Conventions: e.g. this document about documentation, code style
• System Design: e.g. network stack, compositor, kernel, assumptions
• APIs: e.g. FIDL protocols, library functions, syscalls
• Protocols: e.g. schemas, encodings, wire formats, configuration files
• Tools: e.g. bootserver, netcp, fx
• Workflows: e.g. environment set up, test methodologies, where to find various parts, how to get work done

Where should I put documents? What goes where?

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:

• Zircon specific documentation should be created in /zircon/docs.
• Fuchsia documentation that is not specific to Zircon specific should be created in /docs. In the /docs/ directory, you should create your documentation or images in one of these sub-directories:
  • best-practices General 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.
  • development Instructions, 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-book Concept and developer guides about the features of Fuchsia. You should organize the content that you create by specific features.
  • images Images that are used in the documentation. You should place images in this common directory and avoid placing images in the same directory as documentation.

What documentation should I create?

Most documentation can be divided into four categories:

• Reference - Information-oriented documentation
• Conceptual - Understanding-oriented documentation
• Procedural
  • How to - Goal-oriented documentation
  • Codelab - Learning-oriented documentation

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.

What documentation style guidelines should I follow?

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.

How can I expose my documentation?

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:

• Top-down linkage: Add links from more general documents to more specific documents to help readers learn more about specific topics. The Fuchsia book is a good starting point for top-down linkage.
• Bottom-up linkage: Add links from more specific documents to more general documents to help readers understand the full context context of the topics being discussed. Adding links from module, class, or protocol documentation comments to conceptual documentation overviews can be particularly effective.
• Sideways linkage: Add links to documents on subjects that help readers better understand the content of your document.