Skip to content

Commit

Permalink
Add guideline categories (#12)
Browse files Browse the repository at this point in the history
Some guidelines are more important to follow than others; some
guidelines have alternatives which may be preferable depending on the
circumstance. To clarify how guidelines ought to be followed, define
importance levels/categories, and assign each guideline to one in the
"meta" guidelines document as an example. These categories are inspired
by the [Redux Style Guide](https://redux.js.org/style-guide/#rule-categories)
as well as the classifications in the [TTS Best Practices Guide](https://engineering.18f.gov/about/).
To prevent from having to create separate category sections in each
guidelines document, I've opted to associate an emoji with each
category.
  • Loading branch information
mcmire authored Dec 1, 2022
1 parent ec6e847 commit cf5fb97
Showing 1 changed file with 17 additions and 9 deletions.
26 changes: 17 additions & 9 deletions guides/guidelines.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,30 @@
# Guidelines for Writing Guidelines

## Use this template as a guide
## 🙏 Use this document as a guide

This document is not only a set of guidelines, but also a template for other guidelines documents.

## Be direct
## 🙏 Communicate the importance of your guideline

Guidelines may differ in how closely they are intended to be followed. To designate the importance of a guideline, include an emoji in its header to assign it to one of three categories:

1. **🙏 (Standard):** These are guidelines that it really behooves everyone to follow. There shouldn't be a reason not to follow them, but anyone who feels that a guideline should be changed or removed should start a discussion in a pull request.
2. **🌳 (Recommended):** These are guidelines that everyone ought to follow, though teams or projects may opt to bypass or change them if they have a good reason to do so.
3. **💡 (Suggested):** These are guidelines that offer one way to solve a problem among multiple, equally valid alternatives. When you are writing such a guideline, enumerate these alternatives and suggest one of them for the reader to follow.

## 🙏 Be direct

Guidelines should be as easy to understand and follow as possible. Think of each guideline like a commit: start with a concise summary, preferably a direct command, then use a paragraph or two to elaborate.

## Be succinct
## 🙏 Be succinct

Remove extraneous language in both the guideline itself and the elaboration (see [*The Elements of Style*](https://www.gutenberg.org/files/37134/37134-h/37134-h.htm#Rule_13) for help).

## Bolstering your guideline, if necessary
## 🙏 Bolster your guideline if necessary

If a discussion exists in Slack or GitHub which spawned your guideline, link to that discussion. Or, if a book, blog post, or related work exists which can help to shine light on your guideline's utility, link to the resource.

Although not strictly necessary for arbitrary guidelines — where the problems they are solving have multiple possible solutions and none of the solutions have a significant advantage over the other — or for axiomatic guidelines — where the values they express are assumed to be good, such that the absence of these values is assumed to be bad including a context or rationale with your guideline is still helpful for onboarding.
Although not strictly necessary for arbitrary guidelines (which aim to solve problems with multiple, equal-advantage solutions) or for axiomatic guidelines (which abide by values assumed to be good over those assumed to be bad), including a context or rationale with your guideline is still helpful for onboarding.

Here is an example:

Expand All @@ -26,11 +34,11 @@ Here is an example:
[**View discussion on GitHub**](https://example.com).
```

## Provide examples
## 🙏 Provide examples

It is far easier to understand a principle not by reading about it, but by observing its effects.

A common way to provide an example is to offer a dichotomy: a passage of code which does not follow the guideline followed by a passage of code that does. Understanding that some decisions are arbitary, care must be taken not to use language like "bad" or "good" which could be taken as a slight against the reader's skill level. Rather than assigning a grade to the code in question, tell the reader what to do.
A common way to provide an example is to offer a dichotomy: a passage of code which does not follow the guideline followed by a passage of code that does. Understanding that some decisions are arbitary, take care not to use language like "bad" or "good" which could be misread by others as a slight against them. Rather than assigning a grade to the code in question, tell the reader what to do.

For instance, instead of this:

Expand Down Expand Up @@ -64,6 +72,6 @@ const THE_MEANING_OF_LIFE = 42;
```
~~~

## You can change these!
## 🙏 Be empowered to propose your ideas/suggestions

The guidelines in this repository are not set in stone. If you disagree with a guideline, or you notice a guideline that's missing, feel free to create a pull request.
The guidelines in this repository are not set in stone, and none of us is the gatekeeper. If you disagree with a guideline, or you notice a guideline that's missing, feel free to open a discussion in a pull request.

0 comments on commit cf5fb97

Please sign in to comment.