Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: use RFC 2119 keywords #9532

Merged
merged 6 commits into from
Jun 22, 2021
Merged

docs: use RFC 2119 keywords #9532

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
21b7035
docs: use RFC 2119 keywords
robert-zaremba Jun 17, 2021
681a4ab
Update docs/architecture/README.md
robert-zaremba Jun 21, 2021
4ef76d3
rephrase RFC 2119 usage
robert-zaremba Jun 21, 2021
b97c7c4
lint markdown
robert-zaremba Jun 21, 2021
4780a2c
Merge branch 'master' into robert/rfc-2119-keywords
robert-zaremba Jun 21, 2021
1676a65
Update docs/DOC_WRITING_GUIDELINES.md
robert-zaremba Jun 21, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/DOC_WRITING_GUIDELINES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
+ Don't abuse `code` format when writing in plain English.
+ Follow Google developer documentation [style guide](https://developers.google.com/style).
+ Check the meaning of words in Microsoft's [A-Z word list and term collections](https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms) (use the search input!).
+ Use RFC keywords: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I totally agree that we should use these definitions for ADRs, but less sure about docs in general. It might read too much as a formal spec, whereas docs should keep a pleasant side.

My proposal is to remove these definitions for docs, only keep for ADRs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
+ Use RFC keywords: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
+ It is recommeneded to use RFC keywords: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).

maybe just a recommendation?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My proposal is to remove these definitions for docs, only keep for ADRs.

I agree. These keywords are meant for use in RFCs, not in user documentation.

maybe just a recommendation?

I think this would be better but still misleading. I do not think we should be recommending the use of capitalized RFC key words when writing user documentation.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I rephrased it. Could you re-check?


## Technical Writing Course

Expand Down
6 changes: 6 additions & 0 deletions docs/architecture/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,12 @@ If recorded decisions turned out to be lacking, convene a discussion, record the

Read about the [PROCESS](./PROCESS.md).

#### Use RFC 2119 Keywords

In many documents several words are used to signify the requirements in the specification. These words are often capitalized: "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL. They are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
robert-zaremba marked this conversation as resolved.
Show resolved Hide resolved



Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should'nt the markdown linter catch these?

Suggested change

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be fixed with make lint-fix. Maybe we should be automatically running this in the CI?

## ADR Table of Contents

### Accepted
Expand Down