ced04c7cec
Summary: This diff includes minor changes to the pages within the Under the Hood section of Flipper Docs. The page Creating Plugins -> Desktop Plugin APIs -> QPL Linting -> Building a Linter is now removed from the sidebar. Reviewed By: lblasa Differential Revision: D41533283 fbshipit-source-id: 63e50210815fe2b67ea54991eb8a7bc16e04e1be
67 lines
3.8 KiB
Markdown
67 lines
3.8 KiB
Markdown
---
|
|
id: documentation-standards
|
|
title: Flipper Docs Standards
|
|
sidebar_label: Flipper Docs Standards
|
|
description: Provides a set of standards requirements to persist documentation standards
|
|
keywords:
|
|
- Flipper docs standards
|
|
- Flipper docs rules
|
|
---
|
|
import useBaseUrl from '@docusaurus/useBaseUrl';
|
|
|
|
## Key standards
|
|
|
|
The Flipper Docs team is committed to writing docs that serve users. To measure and maintain satisfactory documentation quality, the following key standards are used:
|
|
|
|
| [Completeness](#completeness) | [Discoverability](#discoverability) | [Accessibility](#accessibility) | [Accuracy](#accuracy) |
|
|
|:--|:--|:--|:--|
|
|
| Is the information sufficient to give the reader a good understanding or to provide a solid solution to a problem? | If the information exists, is it easy to find? | Is the information accessible to readers of different capability? | Is the information accurate and up to date? |
|
|
|
|
To help you achieve each of these standards, several points for consideration are listed in the following sub-sections (or you can select a column header to link to its sub-section).
|
|
|
|
### Completeness
|
|
|
|
Completeness is determined by how many questions, and the type of questions, the reader may have after reading your document. For example, if after reading a Flipper document on 'getting help and providing feedback', the reader asked the question "Where do I go if I'm a noob?" then the document might not be complete.
|
|
|
|
To increase your document's completeness, consider the following:
|
|
|
|
* Limit Assumptions.
|
|
* Trade-offs and limitations of APIs and approaches should be discussed openly.
|
|
* Where possible, describe alternatives to what you're describing: understanding the available options empowers people to feel confident in their choices.
|
|
* Give tips you think are particularly useful.
|
|
* The user shouldn't have to navigate to different documentation sources (such as Wiki pages and posts) to gain a core understanding.
|
|
* Explain what success looks like.
|
|
* The discussion of a technical topic shouldn't be in the 'Getting Started' section.
|
|
* Is each step explained, or does it rely on other knowledge?
|
|
* Empathize with the reader. Consider questions such as: "*Are they trying to learn how to do something?*" and "*Has something gone wrong and they're trying to figure out if a solution is possible?*"
|
|
|
|
### Discoverability
|
|
|
|
Discoverability is the degree to which a piece of information (instruction, guideline, code snippet, and so on) can be found within the Flipper Documentation website.
|
|
|
|
To improve your document's discoverability, consider the following:
|
|
|
|
* Add appropriate keywords to your file. The keywords are used by Static Doc's search tool.
|
|
* Is the information easy to find. Test for keyword searches to see if and where in the result list your documentation is listed.
|
|
* Consider the placement of the file (if you're adding a new one).
|
|
|
|
### Accessibility
|
|
|
|
Accessibility is the measure of how easy it is for users of different capability to read, understand and navigate your documentation.
|
|
|
|
To improve your document's accessibility, think about the following:
|
|
|
|
* Is non-standard terminology fully defined before being used (this includes the use of abbreviations).
|
|
* Is it easy to understand and apply the documented information?
|
|
* The most effective medium (words, diagrams, images, videos, examples, or a combination).
|
|
|
|
### Accuracy
|
|
|
|
Accuracy is determined by how relevant, correct, and up to date the content of your documentation is.
|
|
|
|
To ensure your document's accuracy, think about the following:
|
|
|
|
* Ensure that all 'Live' code samples are relevant to the topic being covered and provide appropriate output.
|
|
* Explain the relevant aspects of the snippet functionality clearly.
|
|
* When making any changes to procedure, architecture, or code, make the documentation of those changes part of the change request.
|