Style Guide

This document hopes to clarify the way we talk about the things we do.

Write the Docs

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

Meetups

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

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”.

Website content

Our website uses mostly reStructured Text (RST) markup format. We still have some legacy content in Markdown but we try to retire it whenever we encounter it.

Here are some guidelines when writing RST content for the WTD website:

  • Use one-sentence-per-line and do not break sentences across multiple lines.
  • If you are cross-referencing to a different page within our website, use the doc directive and not a hyperlink.
  • If you are in doubt about how to tag titles, lists, or anything else, the About the Write the Docs organization is a good example for how we tag our content files.