From 7269c7c70e70264efb5c7f3424db4606f22b23f6 Mon Sep 17 00:00:00 2001 From: Elliot Winkler Date: Mon, 17 Jul 2023 22:55:01 -0600 Subject: [PATCH] Update guidelines for guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit There are a couple of issues with the "meta-guidelines": 1. Currently, if you want to assign a guideline to a category, you must use an emoji in the guideline header. There are two problems with emoji: they are difficult to work with — try selecting one in your editor! — and, like icons, they can mean different things to different people. 2. Originally we borrowed the concept of guideline categories from the Redux Style Guide. This guide lists three of them: Essential, Strongly Recommended (renamed to "Recommended" here), and Recommended (renamed to "Suggested"). However, there is not a clear delineation between these categories — when do you know whether to assign something as Recommended vs. Essential? — and anyway, we've only used the first and third categories so far. 3. The guideline that describes how to present a dichotomy — a non-recommended way to do something and a recommended way to do it — allowed for unclear wording. 4. The "be empowered" guideline isn't really a guideline, it's just a nice thing to say. And it really applies to the whole repo, not just the guidelines. To solve these issues: 1. I've simplified the concept of guideline categories. There are only two. All guidelines are essentially rules by default. If a guideline presents options for addressing a pain point, they can be called out by using an emoji. 2. I've simplified the instructions on how to give examples. 3. I've removed the "be empowered" guideline. I may add that to the root README and also explain how to propose new changes. --- guides/guidelines.md | 76 +++++++++++++++----------------------------- 1 file changed, 25 insertions(+), 51 deletions(-) diff --git a/guides/guidelines.md b/guides/guidelines.md index 45247da..78b861f 100644 --- a/guides/guidelines.md +++ b/guides/guidelines.md @@ -1,77 +1,51 @@ # Guidelines for Writing Guidelines -## 🙏 Use this document 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. -## 🙏 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 +## 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 - -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). +## Be succinct -## 🙏 Bolster your guideline if necessary +Remove extraneous language in both the guideline itself and the elaboration. -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. +## Bolster your guideline if necessary -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. +If a discussion exists in a public GitHub repository which provides context around a guideline, link to that discussion. Or, if a book, blog post, or related work exists which helps to explain the purpose of a guideline, link to the resource. -Here is an example: +Use a "Read more" section to collect multiple resources: ``` markdown -## Use snake-case to name files and directories. +### Read more -[**View discussion on GitHub**](https://example.com). +- [Link 1](https://example1.com) +- [Link 2](https://example2.com) +- [Link 3](https://example3.com) ``` -## 🙏 Provide examples +## Provide examples -It is far easier to understand a principle not by reading about it, but by observing its effects. +It is far easier to understand the purpose and effects of a guideline not by reading about it, but by observing an example. -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. +A common way to provide an example is to offer a dichotomy, a passage of code which falls outside the guideline followed by a passage of code that conforms to it. Understanding that some decisions are arbitrary, take care not to use language like "bad"/"good", "incorrect"/"correct", etc., which may sound judgmental. Rather than assigning a grade to the code in question, use emoji: -For instance, instead of this: + 🚫 -~~~ markdown -**Bad:** + ``` javascript + const x = 42; + ``` -``` javascript -const x = 42; -``` - -**Good:** + ✅ -``` javascript -const THE_MEANING_OF_LIFE = 42; -``` -~~~ + ``` javascript + const THE_MEANING_OF_LIFE = 42; + ``` -say something like this: - -~~~ markdown -Instead of this: - -``` javascript -const x = 42; -``` - -say this: - -``` javascript -const THE_MEANING_OF_LIFE = 42; -``` -~~~ +## Mark guidelines with options accordingly -## 🙏 Be empowered to propose your ideas/suggestions +By default, a guideline is intended to be followed unless there is a good reason not to do so. -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. +Occasionally, however, a guideline may offer a set of options among which the reader may choose. To designate this type of guideline, prefix the header with 💡.