News for hackers. Stuff that matters.
Re:Ask HN: How do I write good documentation? by kevin_bauer on Monday October 06, 2014 @02:04PM (#8417200)
Technical documentation is hard, really hard. It's easier to explain what not to do.

Some suggestions:

  - It's no prose, so don't try to be arty.
  - Keep it short! 
  - When in doubt, drop it.
  - Use simple words. Not everyone is fluent in English.
  - Any sentence with more then two lines is an anomaly.
  - Be consistent. Avoid surprises.
  - Usecases and Examples are important and may shorten explanations.
  - Include common mistakes and their workarounds.
  - You have to refactor often (>>20x).
  - Use a versioning system like git or mercurial.
  - Avoid abbreviations and introduce them at first occurence e.g:
    concurrent versioning system (CVS)
  - A colum shouldn't exceed 9-12 words (~60 chars) to improve readability.
  - Keep your rules in a file (e.g: doc.playbook) and check them
  - Let others proof read, or yet better find an editor.
  - Try to be gender agnostic. Why? cautionary tale:
    https://github.com/joyent/libuv/pull/1015

There are no comments on this comment yet.