Technical documentation guidelines
  • 04 Mar 2022
  • 6 Minutes to read
  • Dark
    Light

Technical documentation guidelines

  • Dark
    Light

The Ant Media documentation is the single source of truth for all information related to Ant Media development, implementation, usage, and troubleshooting. It evolves continuously, in keeping with new products and features, and with improvements for clarity, accuracy, and completeness. 

Top 10 writing tips before you start

Use bigger ideas, fewer words

Our modern design hinges on crisp minimalism. Shorter is always better. 


Example: 


  • Replace this: If you're ready to purchase Ant Media Enterprise Edition for your organization, contact one of our sales people.
  • With this: Ready to buy? Contact us.

Write as you speak

Read your text aloud. Does it sound like something a real person would say? Be friendly and conversational. No robot words.


Example: 


  • Replace this: “No stream exists”
  • With this: “No stream exists. This either means …. or ….. Please contact our troubleshooting guide for more information.”

Get to the point fast

Lead with what’s most important. Make customer choices and next steps very obvious and easy to follow.

Be brief

Give customers just enough information to make decisions confidently. Prune every excess word. 

When in doubt, don’t capitalize

Default to sentence-style capitalization, and capitalize only the first word of a heading or phrase and any proper nouns or names. Never Use Title Capitalization (Like This), in Ant Media blogs, technical documentation or web page headers.

Using space

Use only one space after periods, question marks, and colons. Do not use space before ( and after ).

1. Topic types

There are different types of topic types in Ant Media documentation, including concepts, tasks and troubleshooting. 

1.2 Concept or feature 

Such topics introduce a single feature or concept. It should answer the questions: 


  • What is this? 
  • Why would I use it?

 

Think of everything someone might want to know if they’ve never heard of this concept before.

Don’t tell them how to do this thing. Tell them what it is.

If you start describing another concept, start a new concept and link to it.

Example: 


Title (a noun, like "Applications")


A paragraph that explains what this thing is.


Another paragraph that explains what this thing is.


Remember: if you start to describe another concept (e.g VOD), stop yourself.

1.3 Task 

A task gives instructions for how to complete a procedure.


Title (starts with -ing form of a verb, like "Creating an application")


Do this task when you want to...


Prerequisites (optional):


- Prerequisite 1

- P2

- P3


To do this task:


1. Location then action. (Go to this menu, then select this item.)

2. Another step.

3. Another step.


Task result (optional). Next steps (optional).

1.4 Troubleshooting

Troubleshooting information should be in this format:


Title (the error message or a description of it)


You might get an error that states <error message>.


This issue occurs when...


The workaround is...

2. Things to look for when you write

2.1 Punctuation

  • Use a period after every bullet point that is a sentence.
  • Use sentence case for titles, headings, labels, menu items, buttons. 
  • Always capitalize the first word in bulleted lists. 
  • Use a period after every bullet point that is a sentence.
  • Use no punctuation after bullets that are not sentences.
  • Use: it’s, can’t, wouldn’t, you’re, you’ve, haven’t, don’t 
  • Don’t use: it is, cannot, would not, it’ll, should’ve
  • Use “1, 2, 3” instead of “one, two, three” for numbers.
  • Do not use italics, but use bold for anything you want to emphasize. Italic is harder to stand out.

2.2 Use active voice

Whenever possible, write in active voice, instead of passive voice. Active voice is easier for users to understand and often results in shorter content.

2.3 Brevity

Users will skim content, rather than read the text carefully. Copy should be concise and short whenever possible. A long message or label is a red flag hinting at a design that needs improvement.


Brevity is especially important for:


  • Headers
  • Button text
  • Field labels
  • Error messages

For each of these content types, look for ways you might rephrase text that seems too long. Also, eliminate unnecessary phrases like “in order to” and extra articles like “the” when they don’t add clarity.


Avoid Latin abbreviations, for example: 


  • Instead of “i.e.”, use “that is.”
  • Instead of “e.g.”, use “for example.”
  • Instead of “etc.”, either use “and so on” or consider editing it out, since it can be vague.

2.4 Point of view

In most cases, it’s appropriate to use the second-person point of view, because it’s friendly and easy to understand.


The words “you,” “your,” and “yours” indicate that you’re writing in second person. It’s important to note that in UI copy, the “you” is often implied rather than stated.


To write in second person, focus on eliminating words like “can” or “will” from content.


Example: use “To get started, click the Settings page on the AMS panel.” instead of ”Users can get started by clicking the Settings page on the AMS panel.”

2.5.1 Above

Try to avoid using above when referring to an example or table in a documentation page. If required, use previous instead. For example:


In the previous example, we show how to use adaptive bitrate in an iOS application.


Do not use above when referring to versions of the product. Use later instead. For example, use:


  • In Ant Media 2.3 and later…


Instead of:


  • In Ant Media 2.3  and above…
  • In Ant Media 2.3  and higher…

2.5.2 And so on 

Do not use “and so on”. Instead, be more specific. 

2.5.3 Below

Try to avoid below when referring to an example or table in a documentation page. If required, use “following” instead. For example:


  • The following example shows how to deploy using cluster mode.

2.5.4 Beta

Use uppercase for Beta. For example: 


  • The Tensorflow feature is in Beta. 
  • The Ant Media Enterprise Edition Beta release is ready to test.

2.5.5 Checkbox

Use one word for checkbox. Do not use “check box”.


You select (not check or enable) and clear (not deselect or disable) checkboxes. 

2.5.6 Click

Do not use click. Instead, use select with buttons, links, menu items, and lists. Select applies to more devices, while click is more specific to a mouse.

2.5.7 Dropdown list

Use “dropdown list” to refer to the UI element. Do not use “dropdown” without “list” after it. Do not use drop-down (hyphenated), dropdown menu, or other variants.

2.5.8 Earlier

Use “earlier” when talking about version numbers. For example, “In Ant Media 2.3 and earlier”

3. Words to avoid

  • Easily (it may be easy for you but not others)
  • Handy (just like the example above)
  • E-mail (instead use “email”)
  • Enter (instead, use “type”)
  • etc.
  • Foo
  • Future tense (e.g do not use “will display”)
  • Hit (do not use instead of Enter)
  • I (do not use first person singular)
  • In order to (instead, use “to”)
  • Log in or log on (instead, use sign in)
  • “You need to..” (instead, use should or must)
  • Please
  • (s) (example: select the options you want)
  • Self-hosted (instead, use self-managed)

Ant Media related words: 

  • Do not use “Enterprise license”. 
    • Instead use “Enterprise Edition license”.
  • Do not use “Cluster License” 
    • Instead use “cluster license”
  • Do not use “Ultra-Low Latency Streaming”
    • Instead use “Ultra-low latency streaming”

4. Content items

Headings

  • Add only one h1 in each document
  • Start with an h2 and respect the order h2 > h3 > h4 > h5 > h6. 
  • Avoid putting numbers in headings
  • Leave exactly one blank line before and after a heading.
  • Use sentence case (only first letter is upper-case)

Anchor links

  • Do not use absolute URLs like to cross-link to other documentation in the same project.

Navigation 

  • When documenting how to navigate through the Ant Media documents:
    • Always use location, then action.
      • Example: From the Applications list (location), select the application (action).
    • Be brief and specific. For example:
      • Do: Select Save.
      • Do not: Select Save for the changes to take effect.
    • If a step must include a reason, start the step with it. This helps the user scan more quickly.
      • Do: To view the changes, in the merge request, select the link.
      • Do not: Select the link in the merge request to view the changes.

Names for UI elements

UI elements, like button and checkbox names, should be bold


Images

Images, including screenshots, can help a reader better understand a concept. However, they should be used sparingly because they tend to become out-of-date.


When needed, use images to help the reader understand:


  • Where they are in a complicated process.
  • How they should interact with the application.

When you capture an image in Document360, use the style “rounded, bordered, shadow” (all enabled). 

Try to add callouts. The color is red, line width is 3, style is arrow. Example: 



Consider using PNG instead of JPG.


Alert boxes

Alert boxes are generated when one of these words is followed by a line break:


  • NOTE: Use notes sparingly. Too many notes can make topics difficult to scan.
  • WARNING: Use a warning to indicate deprecated features, or to provide a warning about procedures that have the potential for data loss.
  • INFO: (Marketing only): Used to add information relating to sales and marketing efforts.
  • DISCLAIMER: Use to describe future functionality only.


Deprecated features

When a feature is deprecated, add (DEPRECATED) to the page title or to the heading of the section documenting the feature.


Community Edition vs Enterprise Edition


When denoting a feature that is only available in Enterprise Edition, this must be mentioned as a subscript, 8 pt, yellow background right next to the corresponding header. 


5. References

This document is largely based on the following resources: 





Was this article helpful?