Home »

Style Guide¶

This style guide specifies how we write on the Write the Docs 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 (-).

Links ¶

If you are cross-referencing to a different page within our website, use the :doc: directive and not a hyperlink.

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.

On the general website, we aim to take a neutral but friendly tone. Some of the guides distill wisdom from the community, usually shared first in Slack, but we try to present them in a less conversational way.

Among other things, this means you need to take the following into consideration:

Try to stay impersonal but welcoming.
Avoid enforcing personal preferences.
Avoid advocacy and plugs for any specific tools. Discussing pros and cons can work in context.
Use inclusive language. Our community is multicultural, multiracial, multigendered, and generally diverse.

Content ¶

Naming conventions (titles)¶

We use sentence case for page titles and sub-headings (H2, H3). We do capitalize 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, some events are named after the city, others after the country.

Our 2026 conferences are officially called:

Write the Docs Australia 2026
Write the Docs Berlin 2026
Write the Docs Kenya 2026
Write the Docs Portland 2026

Good:

We have some announcements about Write the Docs Portland.
Write the Docs Portland 2027 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.