Skip to content

Styles

Jump to bottom
Deborah edited this page May 17, 2022 · 35 revisions

n8n docs writing style

We base our styles on the Microsoft Writing Style Guide

Quickstart

Formatting

  • Headings: sentence case (more info)
  • UI elements: bold (more info)
  • User input: bold, with italics for placeholders (see User input part way down this page for more info)
  • Make sure you match brand names precisely. For example: "GitHub", not "Github".

Numbers

Write zero to nine in letters, 10 and above in numerals.

More info

Links

All links open in new tab. Use the following syntax:

[link name](link-url){:target="_blank" .external}

Indicate external links using a class, like so:

[commits](https://github.com/n8n-io/n8n/compare/[email protected]@0.177.0){:target="_blank" .external-link}

Note that the .external-link class currently doesn't do anything. However, it effectively tags all external links, making them easy to find - and to re-style in future if we want to.

Screenshots

Use screenshots sparingly. The incur maintenance load.

Any information in a screenshot must also be described in text.

If your contribution includes screenshots, please make sure that they meet the following criteria:

  • Provide alt text
  • Only the Editor UI appears in the screenshot. Anything else, like the browser frame, tabs, and so on, should be omitted.
  • After zooming in once, the Editor UI is 23 boxes wide and 9 boxes tall.
  • The nodes have a distance of two boxes between them.
  • The nodes fit inside the boxes (as much as they can).
  • The workflow is centred in the Editor canvas.
  • If the workflow uses a Trigger node, the Start node doesn't appear in the Editor canvas.
  • In recorded GIFs, the cursor movements in the GIF are slow and easy to follow. A good rule of thumb is that the speed should be about 75% of your regular speed. In any case, make sure that GIFs capture every step of the process at a steady pace.
  • Optimize your images. PNGs can use TinyPNG for quick optimization.

Linting

n8n uses Vale to lint documentation. Linting supports writing quality, and helps writers use the style guide.

The setup comprises:

  • A .vale.ini file in the root of the repo, containing the configuration
  • A styles directory, containing the style definitions. This includes off-the-shelf style libraries for Microsoft, write-good, and alex.

Using Vale

Vale can be run locally (on your machine) or remotely (as part of a CI process) Due to the current state of the docs, we are holding off on implementing the Vale GitHub Action in our CI.

Running Vale locally

  1. Follow the Vale docs to install Vale CLI
  2. Choose whether to lint from the command line, or install a text editor plugin:
    1. Running vale --glob='*.md' docs will lint all Markdown files in the docs directory
    2. Or install a plugin and view problems automatically in your text editor. Browse the docs to see options.

Writing tips

  • Plain language:
    • Clearly explain each step of the process you are documenting.
    • Use present tense, active voice, and "you"-form to address the readers.
    • Keep your writing as concise as possible. Hemingway is a free browser app to measure language complexity. There is no fixed rule about what grade to aim for, but the lower the reading grade, the better.
Clone this wiki locally