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 the developer documentation of platformOS core and platformOS modules.

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

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

Numbers

Spell out numbers one through nine. Use numerals for numbers 10 and greater. Ordinal numbers (third, 12th), follow the same rule. Spell out numbers at the beginning of a sentence.

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 are 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 needed to improve the readability and scannability of your content.

Code examples

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

Inline
Wrap inline snippets of code with `.

Code samples
To add a code sample, use the code block (triple backticks), followed by the language you want to use, for example:

```html

Add your code snippet and close the block:

```

Liquid code samples
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
  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 insert an image, add it to the app/assets/images directory. Create a directory inside images if needed (if there is no directory created yet for the section you are adding your image to). Once you added the image, insert it into the page like this:

<img loading="lazy" src="{{ 'images/best-practices/qa/list_browsers.png' | asset_url }}" alt="The list of browsers available in your system." />

Videos

Screencasts

Upload the video to Youtube and copy its video ID. For example, the video with the URL https://www.youtube.com/watch?v=zm5Iw7jsyC4 has the ID zm5Iw7jsyC4.

Insert a video into the documentation by adding the ID like this:

{% include 'shared/video', id: 'zm5Iw7jsyC4' %}

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:

• API Reference Documentation Introduction page template
• API Reference Documentation Endpoint page template

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 (as defined in the 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.

Release notes template

Use cases

Use cases describe interactions between the user and the system to accomplish a specific task. Use cases tell users how to obtain the end result. They usually address a technical audience and focus on the problem and the solution, so they should include detailed descriptions of the technical implementation and code examples.

Use case template

Writing for accessibility

We collected the guidelines we follow to ensure better accessibility here.

Guidelines for structuring your content

• Use headers for structuring your content: The Markdown format you write in is translated into semantic HTML to help screen readers navigate through our content. Use headers as described in the style guide and follow the templates we provided to ensure consistency. Never skip a header level for styling reasons.
• Improve readability by using concise language, writing short paragraphs, and using lists where applicable.
• Use alternative text for images and icons. Keep in mind that screen readers read this text out loud.
  • If the image serves a function as part of the documentation, describe the image in detail. Users should receive the same information from the alt text that they would have received if they had seen the image.
  • Include the data for charts or graphs in the alt text.
  • Alt text for screenshots where you already described what the user has to do doesn't need to repeat the information.
  • Decorative images don't need alt text — it would only be a distraction.
• If you insert an image, pay attention to the contrast ratio and image quality.

Guidelines for accessible language

Be inclusive and global. Use language that reflects our users' diversity (including, for example, race, gender, ability, location, etc.).

• Use definitions for all terminology: Introduce new concepts by starting with a definition, and add them to the Glossary. Explain acronyms at first use.
• Use technical language: Use the most specific word you can to talk about technical concepts and processes. For example, don't say "take" when you mean "copy" or "clone", don't say "put" when you mean "install", etc.
• Use gender-neutral pronouns: Avoid using gender-specific, third-person pronouns such as he, she, his, and hers. Use the second person when possible, and "they" when needed.
• Use informative link text: To help keyboard navigation, add the information into the link text. For example, instead of writing "learn more" or "click here", write the topic title.
• Avoid ableist language: Don't use words that assume an ability the user might not have (for example, "as you can see" implies the user has a capacity for vision). Avoid directional language, for example, "blue button" or "button below the headline".
• Don't perpetuate racism, bias, and harm: Replace terms like "blacklist" and "whitelist" with terms like "allowed" or "blocked". Replace "native" with "built-in". Note: If the application you describe includes these terms, you have to use them in the documentation for clarity and consistency.
• Avoid metaphors and colloquialisms.

Resources for accessibility

• 18F Accessibility Guide with further links to resources
• Moving beyond empathy: a11y in documentation by Alexandra White
• Don't Say Simply by Jim Fisher