Documentation is an important part of any product or feature because it lets users know how to use a feature that has been implemented. This document is a quick and easy reference for types of documentation.
For information on general documentation standards, including file types, locations, and general tone, see the Fuchsia documentation standards. For specific guidance on word choice, style, and structure, see the Fuchsia documentation style guide.
Procedures (guides), concepts, or reference documentation
Most documentation can be divided into these categories:
- Procedures (guides)
- Get-started - Documentation that provides a step-by-step process for setting up a part of
the Fuchsia developer environment, such as downloading and building Fuchsia. These are located
under
/docs/get-started. - Development, or Guides - Documentation that provides a step-by-step process for completing
any task related to Fuchsia. These are all located under
/docs/development/.
- Get-started - Documentation that provides a step-by-step process for setting up a part of
the Fuchsia developer environment, such as downloading and building Fuchsia. These are located
under
- Concepts - Documentation that helps you understand a concept such
as mods in Fuchsia. This type of documentation is located under
/docs/concepts. - Reference - Documentation that provides a source of information about
parts of a system such as API parameters or FIDL. These are located under
/docs/reference/. Much of the reference documentation is auto-generated.
You should write a procedural document if you plan on explaining to a user how to use a specific feature and are able to guide a user through simple numbered steps. Procedural documents tend to reinforce the concepts that were explained in a conceptual document by giving one or more examples that might be useful for users.
You should write a conceptual document if you plan on explaining a concept about a product. Conceptual documents explain a specific concept, but for the most part they do not include actual examples. They provide essential facts, background, and diagrams to help your readers build a foundational understanding of a product or topic. You should not explain industry standards that your audience should be familiar with, for example, TCP/IP. You might explain how this concept ties in with your feature, but you should not explain the basics behind that industry standard concept.
You should write a reference document if you need to provide information about parts of a system including, but not limited to APIs and CLIs. Reference documentation should allow the user to understand how to use a specific feature quickly and easily.
Procedural documentation
Procedural documentation should try to be brief and each task within your documentation should try to avoid going above 10 steps. You should divide long procedures into multiple sub-tasks to try to keep tasks manageable for a user.
For example, if you wanted to write a procedural document for taking care of a dog, you might have a table of content that looks like this:
How to take care of a dog:
- Feed a dog
- Wash a dog
- Trim a dog's nails
- Brush a dog's hair
General procedural documentation guidelines
- Each task or subtask should have a paragraph that lets a user know what the task is about and what a user should be able to do after performing the task or subtask.
- Use screenshots or graphics to assist a user in navigating a user interface (UI).
A procedural document should not have to explain any concepts to a user, but should reference conceptual documents in case a user does not know about a certain concept. For example, a procedure with a reference to a conceptual document might look like this:
Configure the server with the appropriate configuration. For more information about server configurations, see "server configuration".
Avoid giving the users multiple paths to select when working through procedures. When you avoid giving the user choices, your documentation should lead all users to the same end result.
If a procedural document is meant for beginner users, avoid adding procedures that you might consider better suited for advanced users. If your document is intended for advanced users, state that up front and give them a list of prerequisites before they go through your how to or codelab.
If you are incorporating code samples in your procedural documentation, review the best practices detailed in Code sample style guidelines
Conceptual documentation
Conceptual documentation should try to be brief and for the most part should not go above 1 page. If you need to write more than one page to describe a concept, consider breaking that concept into sub-concepts by using headings. By keeping your document brief you achieve the following:
- You do not overwhelm your reader with a wall of text.
- You avoid losing the reader while they read your document.
The first paragraph should try to be a brief summary of your document, this should allow the user to quickly read through it, determine what the document covers, and if this is relevant to what they want to learn. If your document has multiple headings, you should include a bulleted list with the high-level headings after this first paragraph.
You should use graphics, images, or diagrams to reinforce certain concepts. The text that comes before and after the graphic should explain what the graphic shows. Images should be saved in a feature specific 'images/' directory or a common 'images/' directory. You should also save the source file of your images in a 'images/src/' directory.
Good conceptual documentation usually includes:
- Description rather than instruction
- Background concepts
- Diagrams or other visual aids (preferably in .png format)
- Links to procedural and/or reference docs
After writing your document, it is good practice to proofread the document, put yourself in the user's shoes (no longer being the expert that developed the feature), and try to answer these questions:
- Does the information in the document explain the concept completely?
- Is there information that is not needed for this concept? If so, remove it.
- Is there unnecessary detail about how things might work in the background?
- If I am the user, is there additional I would have liked to know?
Then, if these questions aren't fully answered, edit your document again.
Reference documentation
Reference documentation should provide information about parts of a system including, but not limited to APIs and CLIs. The style of reference documentation should be the same for all reference documentation of that type. For example, API documentation should define all of the API's parameters, indicate if a parameter is required or optional, and show examples of the use of the API. These examples should be very generic and simple. If you feel like you need a more elaborate example, consider creating a procedural document to reinforce your reference documentation.
For the style guide for API documentation, see the API style guide.