certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: use RFC 2119 keywords (#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)
This commit is contained in:
Robert Zaremba 2021-06-22 02:04:55 +02:00 committed by GitHub
parent 81747b4a9e
commit 856cc5b096
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 5 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/DOC_WRITING_GUIDELINES.md
View File

@ -8,6 +8,7 @@
+ Don't abuse `code` format when writing in plain English. + Don't abuse `code` format when writing in plain English.
+ Follow Google developer documentation [style guide](https://developers.google.com/style). + 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!). + 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!).
+ 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).
## Technical Writing Course ## Technical Writing Course

4
docs/architecture/README.md
View File

@ -36,6 +36,10 @@ If recorded decisions turned out to be lacking, convene a discussion, record the
Read about the [PROCESS](./PROCESS.md). Read about the [PROCESS](./PROCESS.md).
#### Use RFC 2119 Keywords
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).
## ADR Table of Contents ## ADR Table of Contents
### Accepted ### Accepted