Skip to content

Commit 856cc5b

Browse files
docs: use RFC 2119 keywords (cosmos#9532)
## Description Recently when discussing NFT standard we stumbled upon the proper use of keywards such as SHOULD, MAY etc ... Let's add them to our guidelines. --- ### Author Checklist *All items are required. Please add a note to the item if the item is not applicable and please add links to any relevant follow up issues.* I have... - [x] included the correct `docs:` prefix in the PR title - [x] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting)) - [ ] provided a link to the relevant issue or specification - [x] followed the [documentation writing guidelines](https://github.com/cosmos/cosmos-sdk/blob/master/docs/DOC_WRITING_GUIDELINES.md) - [x] reviewed "Files changed" and left comments if necessary - [ ] confirmed all CI checks have passed ### Reviewers Checklist *All items are required. Please add a note if the item is not applicable and please add your handle next to the items reviewed if you only reviewed selected items.* I have... - [x] confirmed the correct `docs:` prefix in the PR title - [ ] confirmed all author checklist items have been addressed - [x] confirmed that this PR only changes documentation - [x] reviewed content for consistency - [x] reviewed content for thoroughness - [x] reviewed content for spelling and grammar - [ ] tested instructions (if applicable)
1 parent 81747b4 commit 856cc5b

File tree

2 files changed

+5
-0
lines changed

2 files changed

+5
-0
lines changed

docs/DOC_WRITING_GUIDELINES.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
+ Don't abuse `code` format when writing in plain English.
99
+ Follow Google developer documentation [style guide](https://developers.google.com/style).
1010
+ 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!).
11+
+ RFC keywords should be used in technical documents (uppercase) and we recommend to use them in user documentation (lowercase). The RFC keywords are: "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).
1112

1213
## Technical Writing Course
1314

docs/architecture/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,10 @@ If recorded decisions turned out to be lacking, convene a discussion, record the
3636

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

39+
#### Use RFC 2119 Keywords
40+
41+
When writing ADRs, follow the same best practices for writing RFCs. When writing RFCs, key 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).
42+
3943
## ADR Table of Contents
4044

4145
### Accepted

0 commit comments

Comments
 (0)