docs: adding documentation writing guidelines (#9366)

* docs: adding documentation writing guidelines

* update

* Apply suggestions from code review

Co-authored-by: Marie Gauthier <marie.gauthier63@gmail.com>
Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com>

Co-authored-by: likhita-809 <78951027+likhita-809@users.noreply.github.com>
Co-authored-by: Marie Gauthier <marie.gauthier63@gmail.com>
Co-authored-by: Ryan Christoffersen <12519942+ryanchristo@users.noreply.github.com>
This commit is contained in:
Robert Zaremba 2021-05-25 17:10:17 +02:00 committed by GitHub
parent f0b7f62237
commit 1de12aae67
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 23 additions and 5 deletions

View File

@ -97,6 +97,8 @@ If you open a PR on the Cosmos SDK, it is mandatory to update the relevant docum
- If your changes relate to the core of the CLI or Light-client (not specifically to module's CLI/Rest), please modify the `docs/interfaces/` folder.
- If your changes relate to a module, please update the module's spec in `x/moduleName/docs/spec/`.
When writing documentation, follow the [Documentation Writing Guidelines](./docs/DOC_WRITING_GUIDELINES.md).
## Forking
Please note that Go requires code to live under absolute paths, which complicates forking.

View File

@ -0,0 +1,16 @@
# 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](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!).
## Technical Writing Course
Google provides a free [course](https://developers.google.com/tech-writing/overview) for technical writing.