Documentation Style Guide

Thank you for contributing to our documentation!

To keep the tone and style of our documentation consistent, we created this style guide that contains organization, writing, style, and image guidelines for both the user and developer documentation of the platformOS solution.

The style guide contains writing guidelines for:

  • Technical content (e.g. language, tone, etc.)
  • Each content type in our documentation (e.g. tutorials, release notes, etc.) and corresponding documentation templates (where applicable)

Writing guidelines

Audience

We have identified the following proto-personas using our product and visiting our documentation site.

Proto-personas are descriptions for the types of users that will be interacting with our documentation site. The user personas help us share a specific, consistent understanding of various audience groups. Proposed solutions can be guided by how well they meet the needs of individual user personas. Features can be prioritised based on how well they address the needs of one or more personas.

Our target audience combines technical and non-technical personas.

Technical personas:

  • Experienced Developers/CTOs: need self-support content, examples, detailed explanations
  • Junior Developers/Site Builders: need onboarding

Non-technical personas:

  • Project Owners
  • Business Analysts/Project Managers

Non-technical personas might use the documentation to validate that pOS is the right system for their projects.

Language, tone and style

Language and spelling

Use U.S. English according to the Chicago Manual of Style.

Correct spelling of product names and technologies:

  • platformOS
  • GraphQL
  • JavaScript

Present tense

Use present tense and try to only use future tense when you need to emphasize that something occurs later, from the users' perspective.

Example:

  • Use: platformOS prompts you to save your changes.
  • Avoid: platformOS will prompt you to save your changes.

Second person

Talk to the users in the second person, and address the user as “you”. Avoid the use of gender-specific, third-person pronouns such as he, she, his, and hers. Avoid the use of we, except when you want to emphasize something that the platformOS team did.
Exception: Use the first-person singular pronoun “I” in the question part of FAQs.

Example:

  • Use: Click ‘Save’ to save your changes.
  • Avoid: The user has to click ‘Save’ to save his changes.

Active voice

Write in active voice. Active voice makes the performer of the action (usually the user) the subject of the sentence. Active-voice sentences are more direct and easier to understand than passive-voice sentences.

Example:

  • Use: Click the ‘OK’ button to save your changes.
  • Avoid: Changes will be saved after clicking the OK button.

Capitalization

Title case topic titles (each major word is uppercase). Sentence case headings (only the initial word is uppercase). Don’t use terminal punctuation in titles and headings unless a question mark is required.

Example:

  • Use: (title) Creating Your platformOS application
  • Avoid: (title) Creating your platformOS application

Capitalize platformOS-specific terms, like Authorization Policy, Property, etc., but don't capitalize generic web development terms such as page, layout, partial.

Punctuation

Use the serial comma (the comma preceding the “and” before the last element in a list) except in titles, headlines, and subheads.

Example:

  • Use: List of all APIs, Liquid filters, and GraphQL schema
  • Avoid: List of all APIs, Liquid filters and GraphQL schema

Lists

Use numbered lists for sequential task steps, and bullet lists for sets of options, notes, and the like. Only use a list if it has at least two items in it.

Precede an ordered or bulleted list with a sentence or phrase ending in a colon.

Begin each item with a capital letter. Complete sentences in a list should have a period at the end. If a line item is not a complete sentence, do not use a period. If you are breaking a sentence into a list, periods aren't necessary.

Be consistent, if possible, when writing the items in the list. Make them "parallel." E.g. start each item with a verb in the same tense and form.

Format

Use Markdown formatting for all documentation content (except auto-generated API reference documentation).

Markdown cheat sheet

Headings

Headings help users find relevant information. (Click here to learn more about the importance of headings.)

Don't use # (h1) headings in your articles, as they should be reserved for article titles.

Use ## (h2) headings to separate important sections of the article. They are automatically anchored, so they make direct linking possible.

Use ### (h3) headings as you see fit to improve readability and scannability of your content.

Code examples

Code examples are probably the most important part of the documentation – the more there are, the better. There is a built-in code highlighter that works for many different programming languages.

Wrap inline snippets of code with `.

To add a code sample, use the code block, followed by the language you want to use:

<h1>Code.ruby = 'awesome'</h1>
<script>
document.write('attack');
</script>

which will result in

<h1>Code.ruby = 'awesome'</h1>
<script>
document.write('attack');
</script>

To add liquid markup examples, wrap the whole block in the {% raw %} tag:


```liquid
{% raw  %}

{% if value != blank %}
  Show my {{ value }}
{% endif %}

{% endraw %}
```

Tables

Use tables to describe tabular data.

Table example

| Unit          | Shortcut                       |
|---            |---                             |
| Mile          | `mi` or `miles`                |
| Meter         | `m` or `meters`                |
| Yard          | `yd` or `yards`                |

If you have trouble remembering the syntax, don't worry, just use a Markdown Tables Generator to speed things up.

Paths

When referring to files in the codebase, always assume that the app directory is root. To make this clear to users, write the whole path including the app directory at first mention, but omit it at later mentions. E.g. first write app/views/pages, later views/pages or pages directory.

Conditional sections

By setting specific flags in page metadata you can decide what will be autogenerated for this particular page.

Example

  • questions - bottom questions section with contact us button - default: true
  • contributors - contributors list at the top of the page - default: true
  • feedback - block on the bottom of the page allowing readers to leave feedback - default: true
  • toc - table of contents inserted on the right side - default: false
  • breadcrumbs - path to current page from the root of our site - default: true
metadata:
  title: Contact
  description: Send us a message, and we will get back to you as soon as possible.
  questions: false
  contributors: false
  feedback: false
  toc: true
  breadcrumbs: false

Automatically generated steps

If you have steps in your article, place <div data-autosteps></div> inside of the page.
This will generate steps from h2 headings on that page.

Screenshots, images

Images should be JPG or PNG files. JPEG format is best for photos (images with a lot of colors), PNGs are best for less diverse images. Read more on how to choose format for your image.

Use screenshots to:

  • Visualize the flow/process
  • Visualize a concept
  • Show the result of browser rendering (if helpful)

Don't use screenshots to show:

  • Code (use Markdown code examples instead)
  • Example server response (use Markdown code examples instead)
  • Form configuration view (use Markdown code examples instead)
  • Table with parameters description (use Markdown table instead)

[to be added: information about uploading and linking to images]

Videos

Screencasts

Upload videos to Youtube, and insert the generated embed code. Uncheck "Show suggested videos when the video finishes.", so that the embed code Youtube generates looks like this:

<iframe width="560" height="315" src="https://www.youtube.com/embed/cKbaP-8-VFE" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>

Terminal sessions

Record and share your terminal sessions (where applicable) with asciinema.

Style guides for content types

API reference documentation

Our API reference documentation is auto-generated, and follows our API Reference Documentation templates:

Quickstart guides

Quickstart guides target the newcomer audience segment, and play an important role in the adoption of our product. Because newcomers starting to work with platformOS and implement our APIs face many obstacles (steep learning curve, unfamiliar structure, domain, and ideas behind the API, difficult to figure out where to start), quickstart guides should make the learning process easier for them.

Many users learn best by doing, so a quickstart guide should include steps that walk the user through the process of completing a task. The guide should be short and simple, and list the minimum number of steps required to complete a meaningful task (e.g., creating a platformOS application).

Quickstart guides usually have to include information about the domain and introduce domain-related expressions and methods in more detail. It’s safest to assume that the user has never before heard of our service.

Quickstart guide template

Tutorials

Tutorials are step-by-step walkthroughs covering specific functionality developers can implement with platformOS, or tasks Partners can do on our Partner Portal.

Each walkthrough should be the smallest possible chunk that lets the user finish a task. If a process is too complex, think about breaking it down into smaller chunks. This makes sure that users can get the help they need without going through steps they’re not interested in.

Tutorials teach our users about using platformOS, so include explanations, and link to glossary items, or other content that helps comprehension.

All of our tutorials follow the same format (see tutorial template):

  • Goal: what the tutorial helps the user do, what the user will accomplish by the end of the tutorial
  • Requirements: what background knowledge or resources the user needs to be able to successfully finish this tutorial
  • Steps: brief overview of steps in this tutorial
  • Step 1, Step 2, etc.: detailed descriptions of steps, with screenshots, code examples, etc.
  • Next steps: what the user can do next; if the tutorial is part of a series, link to the next tutorial in the series
  • Questions: contact information for support

Tutorial template

Concept topics

Concept topics provide background information that users must know before they can successfully learn more about or work with a platformOS feature. Often, a concept is an extended definition of a major abstraction such as Pages or Layouts. Concept topics can include examples, graphics, etc.

Concept topic template

Release notes

Our release notes include the following information about each release:

  • new features
  • improvements
  • fixes

Each section lists items in bullet points, and separates in-house development ideas from features, improvements, and fixes suggested by our community.

Release notes template

Questions?

We are always happy to help with any questions you may have.