Formatting Helpdocs

Updated 2 years ago by Michael McKay

Follow this article to correctly format each Helpdoc.

Text formatting

The instructions in this section will give you insight on how to format the text of each article.

Article description

  • For each article, write a short description at the top. This should be 1-4 sentences that describes what the article covers.
  • Font- normal

Step by step guides

  • List each step as "Step 1", "Step 2", etc.- This will make it easier for the reader to locate specific steps
  • Use font H2 for the heading of each step
  • You can use bullet points or numbers in normal font to elaborate on each step
  • You can explain the step in normal font
Make sure to include each step, no matter how small.

Informative articles

These are articles that do not have steps that need to be completed in a specific format. This article that you are reading is an example of an informative guide.

  1. Font- H2 for heading of each section. If you want to create more defined section in the table of contents, you can use H1, H2, and H3 font to create different sections and subsections.
  2. You can use bullet points or numbers in normal front to elaborate on each section. You can also explain the step in normal font without bullet points.
  3. Add a table of contents, so readers can easily navigate the article

Callouts

Use the following callouts to draw attention to important point under steps. Only use callouts for very important items. Using too many callouts will lead to people ignoring them.

Important info
Important tip
Warning

If your article refers another article, you should add an in text link to that article.

  1. Highlight the text you want to link
  2. Click "Link"
  3. Search the name of the Helpdocs article you want to link to. If you want to link to an external website that is not Helpdocs, you can enter the URL in the URL section.
  4. Click "Insert"

Images and screenshots

Use images and screen shots for as many steps as possible. To annotate the images, you should use the Clarify desktop app. Follow the instructions below for how to annotate each image.

Items that need to be clicked

Notate these items with a short red arrow.

Items be moved from one section of the screen to another

Notate these items with a long red arrow.

  1. The side without the arrow head should be the original location of the item that is being moved
  2. The side with the arrow head should point to the new location for the item

Identify an area that you are speaking about in a step, but that does not need to be clicked

Notate these items with red boxes.

Reference multiple steps in images

If an image has multiple steps, you should add numbers to the image in Clarify to notate each step. These steps should correspond to the ordered list in Helpdocs. See the example below:

  1. Click edit button
  2. Enter bedroom info
  3. Click add bed

Sensitive info

Make sure to use the blur tool in Clarify to blur out any sensitive info.

Do not include any access codes or passwords in these documents. These should be kept in Keeper only.

Videos

  • At the bottom of each article, you should embed a video that walks through all the steps in the article
  • When recording the video, talk about each step out loud as you complete it on the screen, so that the person watching the video can follow along
  • Make sure to record the video in a quiet room, so there is no background noise
All videos should be stored in the content Youtube channel or the content Loom. The logins for these are in Keeper.


How did we do?


Powered by HelpDocs (opens in a new tab)