Protobi

← All help posts

View post

## 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](/_questions/487903)**)
    -   what happen when...
-   Blogs and other intellectual curiosities

## [https://www.divio.com/blog/documentation/](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:

```json
{
        "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

## Accordion Blocks

For information that are not necessary, place them under an accordion box.  Can be expanded for more details

Change block text to black because the Accordion has a blue background

```json
{
    "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).

Publishing

Date

Status

Slug edit

Content

Thumbnail

Categories Manage

Tools

AI Database

Publishing

Content

Tools

Danger zone