Under the Hood - Part 4

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

docs/internals/documentation-standards.md

@@ -0,0 +1,66 @@
+---
+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.