Table of contents

Documentation style guide

What pages should be about

Most pages will be about how to do a thing. Include just enough information to allow the reader to complete what they need to do.

Other pages help the reader understand how we use a particular technology or process. This is because they’re working on something that requires that knowledge. Don’t create pages to document why a decision was made if that information doesn’t help the reader complete their task.

Don’t duplicate what’s already in existing documentation.

Title

Put the most important word as near to the start of the title as possible. Short titles are good but descriptive titles are better.

Good examples:

Reboot a machine

Data sync: check failed data

Assets: how they work

Bad examples:

How to reboot a machine

Data sync

Ruby (too vague: what about Ruby?) Don’t use:

  • “how to” at the start
  • ‘ing’ at the end of verbs (for example use ’“deploy an application”, not “deploying an application”)

Structure

Put the 'how to do the thing’ information at the top of the page. Put 'how it works’ stuff lower down.

Subheadings

Use subheadings to break up the page and allow readers to scan the page for what they’re looking for. Don’t repeat the title in the headings though.

Good example:

Title: Rebooting machines

Subheadings: Redis, MongoDB, Elasticsearch

Bad example:

Title: Rebooting machines

Subheadings: Rebooting Redis machines, Rebooting MongoDB machines, Rebooting Elasticsearch machines.

Writing style

Address the reader

Use “you” where possible.

Do say:

You can export data to CSV.

Don’t say:

Data can be exported to CSV.

Acronyms

Spell out acronyms the first time they’re used on the page unless they’re very widely known.

Examples of widely known acronyms:

  • HTTP
  • API
  • XML
  • CSV
  • DNS
  • JSON
  • VPN
  • URL
  • MD5

Example of not widely known acronyms:

DR (disaster recovery)

Bullets and numbered lists

Bullet lists make pages easier to read. Use numbered lists to describe a linear progress, or when the number of items in the list is important.

This page is owned by @tijmen and needs to be reviewed