docs: how to write documentation

[lnielsen]

Write a new section that defines how to write documentation.

• Review examples from other libraries (e.g. django)
• Brainstorm in sprint what the policy should look like.
• Write it :-)

[vlad-bm]

[Draft] Document Structure

• General style and tone
• Writing structure, language and grammar
• Technical writing style guidelines
• Highlighting and formatting
• Code samples
• API documentation
• Test-driven documentation
• Diagrams
• Deprecation, Notes, Warnings
• File structure
  • AUTHORS
  • CHANGES
  • CONTRIBUTING
  • INSTALL
  • README
  • OVERVIEW
  • RELEASE-NOTES
  • init.py
• Do's and Don'ts
• FAQs

[ntarocco]

@lnielsen @slint
I summarized here a few notes that might be useful for us from the technical writing course by Google, I hope it can help:

• acronyms: always spell out the full term before use it extensively
• pay attention when using it,their, this, that` (more details here)
• prefer active voice from passive voice in simple sentences:
  • A wrapper is generated by the Op registration process. -> The Op registration process generates a wrapper.
  • imperative verbs are typically active:Open the configuration file.
• prefer strong verbs: any form of be but also occur and happen are weak verbs.
• limit the use of there is or there are
• write short sentences, limiting subordinate clauses
  • use lists (bullet points or numbered list)
  • use imperative verbs in list items, punctuate items appropriately
• understand when to use which and that
• write great opening sentences:
  • busy readers focus on opening sentences and sometimes skip over subsequent sentences
  • should contain what, why, and how
• Write in the second person. Refer to your audience as "you" rather than "we".
• Place conditional clauses before an instruction, rather than after (See [link to other document] for more information. -> For more information, see [link to other document].)
• Provide text under each heading:

  ## Creating the site
  Some text
  ### Running the carambola command
  Some text
  

• Disclose information progressively