DEV Community

loading...

The dos and don'ts of documentation writing.

duck5 profile image Mr.Duckie ・1 min read

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

Discussion (2)

pic
Editor guide
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!