Skip to main content

Writing Guide

This page contains tips and guidelines on how to create effective documentation that will be valued by your target reader (a measure of its success).

We use StaticDocs, which is based on Docusaurus, for the Flipper documentation website. The StaticDocs homepage is an excellent starting point for information.

Why Documentation Is Needed​

Some of the benefits of documentation include:

  • It's immediately available from the Flipper Documentation website
  • Reduces the number of requests for support.
  • Provides a permanent record of your valuable knowledge.

By making documentation part of your work routine, it becomes less of a burden: the more you write, the easier it gets.

Getting Started​

Often, the most difficult aspect of creating documentation is figuring out how to get started. The following five steps provide some guidance that may help.

  1. Consider your target reader - reflect on questions similar to the following:

    • Why does the reader need this documentation?
    • What is the reader's level of expertise?
    • What is the best way to present the information to the reader?
  2. Create a document outline - create a list of topics you would like to cover that help you to explain the main subject matter. Bearing in mind your target reader, put the topics into the order in which you think they make the most sense: this may involve grouping topics and noting any links between them.

  3. Create a new page - when relevant, create a new page (.md file) in the correct repository folder, making sure you insert the required metadata.

  4. Convert topics into headers - once you've organised the topics, convert them into headers for sections (topic groups) and sub-sections (topics). See below for details of how to use Headers.

  5. Create an introduction - write a brief introduction to your documentation, which states its purpose and an overview of its contents. Your reader will use this to save time and to determine if the document contains the required knowledge or not.

After taking these five steps, you'll have a basic structure for your documentation! The next step is to write the core content, that is, the information that is contained by each header.

Creating the Core Content​

Using the right tone of voice can make your document interesting, engaging, and memorable. The remainder of this page contains guidelines on which tone to use and how to use a range of Markdown features.

Tone of Voice​

'Tone of voice' is the style that you use to communicate the information contained within your documentation, it's like tone of voice you choose to use when speaking with someone. The following guidelines may help you to adopt the right tone of voice in your documentation.

  • Write in the Second Person (You/Your/Yours) - the main benefit is that it increases the readers' sense of involvement in the content and promotes a friendly tone by addressing your reader directly. As a result, your document's reader will find the content more engaging, easier to remember, and easier to understand. Note: this page has been written using the second person.

  • Use First-Person Plural Pronouns (We/Our) sparingly - the main reason is that such pronouns emphasise the writer's team or organisation rather than the reader, which goes against the principle of writing in the second person. The use of 'we' and 'our' can cause distraction or irritation to the reader because the reader might not know which group of people are being referred to with 'we' or 'our'. 'We' could even mean the writer and the reader!

Headers​

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 assist with navigation.

  • Headers indicate document structure - start each main section with a level 2 header. Sub-sections (header levels 3 to 6) should follow a hierarchical structure and be associated with, or relevant to, their parent header.
  • Keep headers short - while keeping your headers as short as possible, make sure they contain enough words to indicate the information contained within the section/sub-section.
  • Keep Headers unique - consider how a header will be listed in the result set of a search from the Static Docs website.
  • Capitalisation of headers - capitalisation should be consistent throughout all Flipper documentation. Headers should be capitalised according to the headline style defined in the Chicago Manual of Style (17th edition).
tip

To ensure you're complying with the Chicago Manual of Style, go to the online tool Capitalize My Title, select the Chicago tab and enter your heading. As you enter the heading, the tool automatically converts it to the Chicago style.

Images​

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:

  • No sensitive or personal data - if you're taking a screenshot that features data, ensure it is test or sample data.
  • Use a lossless format - PNG and SVG files are ideal for websites and PDFs, other formats may look blurred.
  • Use a transparent background - you don't know what colour background your reader will use when reading your documentation. By using a transparent background, you avoid potential colour clashes and unwanted image borders.
  • Avoid coloured borders and shadows - again, you don't know what colour background your reader will use when reading your documentation. A coloured border or a shadow might look great against the colour you are using but could look ugly against a different background.
  • Size for readability - there's little purpose in using any type of image if the text within it can't be read or needs a magnifying glass. Consider splitting your image into two or more images and show how they are connected. If using a screenshot, zoom in on a specific area of the screen and provide context.
  • Be color-consistent - use the same colour and style for callouts and annotations throughout your documentation.
  • Consider dark mode backgrounds - use of a dark mode is becoming increasingly common. With this in mind, test your image using light and dark mode; as a result, you may need to replace black/dark grey colours with pastel-coloured alternatives.
  • Refer to the image - mention the image within the accompanying text. Such as "As shown in the following image...", or "The image below provides an overview of..."
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.

Videos​

Videos are an effective method to present 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.

  • Watch the video - before you use the video in your documentation, watch it to check that its good quality, relevant to the section in which it's located, and provides sufficient information.
  • Keep the content concise - the content of the video should be limited to the specific purpose for which it is being used. For example, if a video is being used to illustrate configuration of a component, it should contain just that process.
  • Refer to the video - mention the video within the section in which it's being used. Also, state the length of the video. For example: "The above video demonstrates the slightly different 'Hg: Show Head Changes' command".
  • State the length of the video - if the length of the video is not shown in the video object, state it in the text. For example, "The above 11-second video demonstrates the slightly different 'Hg: Show Head Changes' command".
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.

Lists​

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'.

Bullet Points​

  • Be concise but effective - use as few words as possible but make sure the meaning is not lost.
  • Capitalise the first word of each bullet.
  • Use emphasis - where possible, emphasise the beginning of the bullet points to give the reader the chance to skim through easily but still get a basic understanding of the content of the list.
  • Use sentences or fragments, not both - within a single list, avoid using bullets that are full sentences mixed with other bullets that are just sentence fragments, phrases, or names.
  • Punctuate consistently:
    • If at least one bullet is a sentence, end all bullets with a full stop. Don't end a bullet with a semicolon (;).
    • If all bullets are phrases, or fragments, use no end punctuation.

Numbered List​

  1. Be clear - keep each item in the list to a specific topic or instruction.
  2. Be logical - the items in the list should follow a logical flow, which guides the reader though the content in a manner that makes sense.
  3. Keep the structure simple - if your list is getting a bit complex in structure or stretches over several pages, consider breaking it up into a series of sub-sections.
  4. Punctuate consistently - each item in the list should end with a full stop, unless the item contains bullet points.

Code Snippets​

Code snippets provide invaluable 'how to' examples to the reader: often, they are copied directly into a Developer's code.

Remember that a snippet is 'a small part or piece of a thing' so keep your snippet short as short as possible and relevant to the section in which it is located.

Markdown Features​

For tips and guidelines on formatting Markdown features, see Formatting Tips.

Resources​

For additional information, see the following resources: