Flipper Docs Standards

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	Discoverability	Accessibility	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.