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.
bootserver
, netcp
, fx
Keep your documentation in the source tree near the things it describes. The location of the document depends on the type of document and its topic.
Preferred locations:
docs
folder at the root of that project's repository and be arranged by topic. e.g. //apps/my-project/docs/my-feature.md
docs
repository itself. e.g. //docs/build_packages.md
Alternate locations:
README.md
to the root of a project's repository may serve as a brief orientation to the project for first time visitors but this is not required.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.
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: