DEV Community

loading...

Discussion on: The dos and don'ts of documentation writing.

Collapse
stereobooster profile image
stereobooster • Edited

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

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
Collapse
duck5 profile image
Mr.Duckie Author

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