Style Guide

This style guide specifies how we write on our websites. It’s just a start, but everything has to start somewhere :)

Technical Formatting

Naming conventions (files and folders)

Files and folder names should be lowercase. Names with multiple words should be separated by hyphens (-).

Website content

Our website uses mostly reStructured Text (RST) and Markdown. Generally more people are familiar with Markdown, so some sections might be written with that if we expect a lot of contributions.

Content

Naming conventions (titles)

For page titles, or Heading1 as they are sometimes called, we use title-case.

If the page includes multiple sub-headings (H2, H3), we usually use sentence-case unless the titles include terminology that is supposed to be capitalized, such as “Writing Day”.

Jargon

Specialized words and jargon should be used sparingly if possible. If jargon is necessary, please define the words so your reader won’t have to search out for the meaning.

Write the Docs (name in use)

We are called Write the Docs. The the is not capitalized.

We do however use the acronym WTD.

Good:

I'm going to Write the Docs.
What happened at WTD last year?

Bad:

I'm going to Write The Docs.
What happened at WtD last year?

Conferences

At the beginning, there was but one Write the Docs. After that, we branched out to a North American and European set of conferences. Now, we see that there may one day be more than one conference per continent, so we started naming the events after the city.

So our 2017 conferences are officially called:

  • Write the Docs Portland 2017
  • Write the Docs Prague 2017

Good:

We have some announcements about Write the Docs Portland.
Write the Docs Portland 2017 will be held again this year.

Bad:

Are you going to Write the Docs North America?
I heard that Write the Docs NA is great.

Inclusive Language

Gendered language should be avoided unless otherwise appropriate. And all content written for Write the Docs should be consistent with the code of conduct.

Meetups

We use one word to refer to our meetups, and it isn’t capitalized unless used in a title.

Numbers

Arabic numerals are generally used to represent numbers. Numbers 1-10 may also be spelled out. Large numbers should be separated with commas.

Abbreviations

Abbreviations should generally be defined before use, especially abbreviations related to tools specialized concepts. Definitions for common abbreviations may also be necessary if their meanings aren’t easily discernible to non-native English speakers.