Software Technical Documentation Best Practices

Posted on Edited on In ,

Principles

  • Oriented toward novices. It is assumed that most of the readers of the document are novices. This way you will write more understandable, in-depth, detailed, and readable.

Structure

  • Overall logic: what, why, how, when, where.
  • Try to break out into detailed subdirectories. You can quickly locate what you want to see.

Details

  • The steps should be clear. Label steps 1, 2, and 3.
  • Try to add links to nouns that you can give links to. E.g. official website, explanation of specialized terms.
  • The code field is to be marked with a code, e.g. code.
  • Use tables as much as possible for structured information.
  • Try to use pictures where you can illustrate to make a clearer and more visual illustration. Don’t mind the hassle. It is more visual and easier to read. For example: UML, flow chart.
  • Give a link to the reference content at the end.

Others

  • After writing, read it through at least once. Timely detection and revision of some statement errors, incoherence; inaccuracy and lack of clarity of expression, and so on.