github.com/cosmos/cosmos-sdk@v0.50.10/docs/DOC_WRITING_GUIDELINES.md (about)

     1  # Documentation Writing Guidelines
     2  
     3  ## Best Practices
     4  
     5  * Check the spelling and grammar, even if you have to copy and paste from an external source.
     6  * Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share.
     7  * Try to express your thoughts in a concise and clean way.
     8  * Don't abuse `code` format when writing in plain English.
     9  * Follow Google developer documentation [style guide](https://developers.google.com/style).
    10  * 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).
    12  
    13  ### Links
    14  
    15  **NOTE:** Strongly consider the existing links - both within this directory and to the website docs - when moving or deleting files.
    16  
    17  Relative links should be used nearly everywhere, due to versioning. Note that in case of page reshuffling, you must update all links references.
    18  When deleting a link, redirects must be created in `docusaurus.config.js` to preserve the user flow.
    19  
    20  ### Code Snippets
    21  
    22  Code snippets can be included in the documentation using normal Markdown code blocks. For example:
    23  
    24  ```md
    25      ```go
    26      func() {}
    27      ```
    28  ```
    29  
    30  It is also possible to include code snippets from GitHub files by referencing the files directly (and the line numbers if needed). For example:
    31  
    32  ```md
    33      ```go reference
    34      https://github.com/cosmos/cosmos-sdk/blob/v0.46.0/server/types/app.go#L57-L59
    35      ```
    36  ```
    37  
    38  ## Technical Writing Course
    39  
    40  Google provides a free [course](https://developers.google.com/tech-writing/overview) for technical writing.