docs/internals/documentation-writing-guide.mdx
import useBaseUrl from '@docusaurus/useBaseUrl';
To assist you in writing your documentation, this page contains tips and guidelines on how to create effective documentation that is valued by your target reader (a measure of its success).
Flipper uses StaticDocs, which is based on Docusaurus, for the Flipper documentation website. The StaticDocs homepage is an excellent starting point for information.
Some of the benefits of documentation include:
By making documentation part of your work routine, it becomes less of a burden: the more you write, the easier it gets.
You may be creating content for a new document or updating the content of an existing document. Whatever the reason, there are two key points to consider before you make any changes:
Both of these key points are detailed in the following sub-sections.
:::note Important
The content of any material you create for any aspect of Meta's documentation must fully comply with Meta's values, policies, and initiatives, and must incorporate Meta's principles of diversity, equity and inclusion.
For details, see the following:
Consider how you'd explain a work-related task to a colleague; the words you'd use and the manner in which you'd say them. Following are some points to consider, which will help you to adopt the write 'tone of voice' in your documentation:
The correct use of pronouns can increase the reader's engagement, enjoyment, and comprehension of the information in your documentation. Following are some guidelines on when to use particular pronouns (it does matter):
Bad spelling and grammar can have a negative effect on the tone of voice in your document (making it irritating to read and difficult to understand).
The problem is that we all make unintentional spelling and grammar errors when writing. Fortunately, there are three steps you can take to reduce (or, hopefully, remove all) those errors:
This is not going to be 100% effective every time, but it will definitely help to get as close to 100% as possible.
Documentation style involves two areas of interest:
The title provides an at-a-glance summary of a page's content. It is also used in the SideBar so assists with navigation of the Flipper Documentation website. Consider the following guidelines before choosing a page title.
Good documentation is split into a series of sections that are logically structured and cover the subject matter. Headings are used for the document's Table of Contents, which provide the reader with an outline of the document and assists with navigation.
To assist with the capitalization of your page's title and headers, go to the online tool Capitalize My Title, then:
As you enter the title/header, the tool automatically converts it to the selected style, which you can then copy/paste into your editor.
For examples of using Markdown for headers, see Markdown Formatting
Code examples are one of the best ways to help your readers take their understanding to the next level by providing them with something they can actually view and experiment with on their own.
:::note Remember that a snippet is 'a small part or piece of a thing' so keep your snippet as short as possible and relevant to the section in which it's located. :::
When providing code snippets, first create an example in the Flipper shell and then directly reference that example in your documentation. This enables the Flipper website to ensure that code in its documentation always stays up-to-date and functional
Make sure there is one blank line between the code snippet and any surrounding text.
For an example of using Markdown for code snippets, see Markdown Formatting
Images includes pictures, diagrams, and screenshots.
The well-known adage "A picture is worth a thousand words." is true but must be accompanied by knowledge of the best way to use images, and an awareness of their limitations. Following are guidelines for the use of images in your documentation:
:::tip Keep in mind that images are meant to complement text, not replace it. Though a picture may be worth a thousand words, the reader still needs the detail contained within the text. :::
The use of some Latin abbreviations (such as 'e.g.', 'etc.', 'i.e.', 'et al.', and so on) should be avoided for the following reasons:
When tempted to use the Latin abbreviations shown in the following table, consider using the English equivalent.
| Latin | English Equivalent |
|---|---|
| e.g. | for example |
| et al. | and colleagues / associates / team members |
| etc. | and so on / and the rest |
| i.e. | that is |
| N.B. | Note |
:::note Key point: whenever possible, use plain, easy-to-understand English in your documentation. :::
Within Flipper Docs, links are usually text-based and can be used to navigate your readers to several types of link targets, such as the following 'good' links:
As can be seen in the link examples above, a link consists of the parts shown in the following table (but not necessarily in the same order).
| Link part | Using the first example, above |
|---|---|
| Leading Phrase | "For information on the type of links to avoid, see" |
| Target description | [Bad links] |
| (Optional) Location | ", below" or "website" |
| Target | (#bad-links) or a URL |
:::tip Tips
It's worth remembering that the reader won't know beforehand where a link is taking them unless it's stated (or at least suggested) in the 'Target description' or the 'Location'.
Therefore, it's not a good idea to use links such as the following:
'Bad' links could lead to navigation confusion, frustration, and loss of comprehension.
For additional guidelines on using Markdown for links, see Markdown Formatting.
If the information you wish to communicate involves a series of steps, follows a defined procedure, or indicates preference or ranking, use a numbered list, which is also known as an 'ordered' list.
If the order of items in the list is irrelevant, use bullet points, which are known collectively as an 'unordered list'.
The bullet points used throughout this page provide examples of the style to be used.
:::note Sometimes, it might not be possible to use an emphasized phrase (the part that is in bold) for each bullet. In such cases, try to apply the other bullet point guidelines to your list. :::
Since Flipper supports multiple platforms, you may need to provide information that is specific to each platform. The Tab tool provides an excellent way of this information via use of the CodeLanguageTabs component.
Tabs provide your reader with an easy method of switching from one platform (or process) to another without having to scroll up and down the page.
For an example of using Markdown for tabs, see Markdown Formatting
Videos are an effective method of presenting a lot of information to the reader. However, just like images, the use of videos must be accompanied by knowledge of how to use them effectively. Following are guidelines for the use of video in your documentation:
:::tip When deciding to use a video, keep in mind that it takes much more time to produce a video than to change some text. A small change to a UI or a process is relatively easy to change in text. The same change in a video may mean it needs to be replaced or removed, which, ultimately, involves much more work. :::
For additional information, see the following resources: