Tutorial Style Guide

Article types

There are several article types we would write and put on our tutorial sites:

• Single action article (Tutorial)
  • e.g. how to create a global filter
• Topic based article (Explanation or reference)
  • e.g. how do all types of filters work
• Curated list of articles (Tutorial or reference)
  • new user training articles
• Q&A (How to guide)
  • what happen when...
• Blogs and other intellectual curiosities

https://www.divio.com/blog/documentation/

Protobi specific 

• Press the square edit icon for element Q18   (i.e. use "press" or "select" rather than "click")
• Select "Compact to..." from the context menu, choose "Checkbox" and press "Ok."  (i.e. menu items in double quotes) 
• Element Q18 has data values 0 and 1, which are formatted as 'No' and 'Yes' (i.e. value labels in single quotes)

Font

Use default font in the theme, this is the easiest way to keep consistency. If a font gets changed for whatever reason, just highlight it and "clear formatting." The button is on the farthest right of the toolbar.

Article Title

Communicates the core teaching of article

Sub Title

Tells a little bit more about what will be discussed in the article. If there seems to be no way to do this without sounding repetitive, (ex. articles explaining short simple tasks) the sub title is not always needed.

Topic heading

Each sub topic should be have an h2 header.  These header also serve as clickable table of content on the right side of the tutorial page.  For single action article, there might not be a heading line. Title of article should not be in the body.

Hero image

Every article should start with a picture.  That first picture can be image of the tool bar, menu button, action dialogues, icons.  That image will be the hero image for the article.

When Hero image and article header should mimic the actual GUI of Protobi

Screen captures

Screen captures should have a custom width in the multiple of 120px.  

• Icons or short width lists - 120px
• Single core element - 240px
• Side-by-side core element - 480px
• custom width element - 240, 360, 480, 600, 720px
• Dialogues - 240, 360 or 480 based on the width of the dialogue
• Full screen capture - 720px

Center images if small (480px or less), left indent if greater than 480px.

Codes

Use standard html code blocks for:

    {
        "title":"programming codes",
        "children":[
        "JSON objects",
        "JS codes in data process",
        "scripts to be entered in dev console"
    }

Be extra careful on syntax.  Need to verify the code works, since they will be copy and pasted

{
    "title":"programming codes",
    "children":[
    "JSON objects",
    "JS codes in data process",
    "scripts to be entered in dev console"
}

Article information

Each article should contain:

• What is the desired outcome
• Where to make the change (+image)
• How to make the change (+image or gif)
• How to undo the change
• (optional) addition insights on the change

Writing style

Don't bury the lede.   

Different articles have different writers, and can have different styles.  Having articles in different style make it less boring to read.

• Just the facts
• Exploration/play/analyze
• Conversational
• Whimsical

Watch out for too many "you" or "your".  It is good to suggest the users can handle the tasks, but don't make it too repetitive.

Similar articles can use similar phrasing for a consistent feel.   But bold/highlight key differences for readability.

Cross-linking articles

When appropriate (and it will be often), link articles whenever something is references.  e.g. when talking about global filters, also link element filters and scenarios.

In big topic discussions, can Insert Article instead of link article to show the single article in its entirety.

Cross-links should open in new tabs if they are EXTERNAL links leading to a different website.

If the link is INTERNAL (e.g., another protobi tutorial on HJ) it should open in the same tab. (Note: articles launched Oct. 16 may not all be currently following this rule, this is in the process of being fixed by review).