Skip to content

Writing Style

This section is still in formative stages. If you're interested in helping to write it, please see issue #8.

Don't Bury the Lede

When writing and editing in this document, consider that once a reader navigates to an article we want to convey the most important point first. Some points may require additional exposition to really motivate the recommendation at hand, but such exposition should follow the articulation of the main point of the article.

Each Article Should Stand on its Own

The structure and organization of this document as a collection of articles means that a reader's attention will be focused on one article at at time.

We are less concerned about "cummulative verbosity" than about each article providing enough context and exposition to make the practice (or principle) clear and accessible without making many assumptions about the reader other than those mentioned in the introduction.

Write Practices in Active Voice

When writing the titles and narrative for a practice, use active voice as much as practical.