The dos and don'ts of documentation writing.

No real reason for this discussion other than the curiosity of how everyone else approaches this task. Any participation is appreciated!

Comments

[stereobooster]

There are a lot of useful style guides (which I need to start to follow):

• developers.google.com/style/
• msu.edu/course/be/485/bewritinggui...
• docs.microsoft.com/en-us/style-gui...
• digitalocean.com/community/tutoria...
• writethedocs.org/guide/writing/sty...

My tips:

• Don't use jargon unless required
• Explain things even if you consider it obvious
• Provide definitions for terms (I like to consult with Merriam-Webster) and full forms of abbreviations
  • If you write series of documents consider creating a reference page with all definitions
• I like to draw pictures (or ASCII art) to accomplish documentation
  • If the picture represents in-precise information I like to use XKCD-style, so reader would treat it as a schematic explanation "on the back of the napkin"
• Provide structure (use headers, headers of different wright)
• Limit the size of the sentence and the size of the paragraph

[Mr.Duckie]

These are great resources and tips! Thanks for your input!