LaconicNetwork/cosmos-sdk
9
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity
ee75c19506
cosmos-sdk/docs/DOC_WRITING_GUIDELINES.md
Robert Zaremba 856cc5b096
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)
2021-06-22 00:04:55 +00:00

1.2 KiB
Raw Blame History

Documentation Writing Guidelines

Best Practices

  • Check the spelling and grammar, even if you have to copy and paste from an external source.
  • Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share.
  • Try to express your thoughts in a concise and clean way.
  • Don't abuse code format when writing in plain English.
  • Follow Google developer documentation style guide.
  • Check the meaning of words in Microsoft's A-Z word list and term collections (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.

Technical Writing Course

Google provides a free course for technical writing.