How to write good code documentation

  • There is no such thing as self-documenting code but your code needs to be self-explanatory. Invest time to review your work and write clean, structured code. It is less likely to contain bugs and will save time in the long run.
  • Ensure you practice continuous documentation within your development process so that it is appropriately prioritized and is written, reviewed and delivered on time with the code.
  • You might write low-level tests for specific scenarios before the code, and leave architecture, user and support documentation to the end of the release cycle when all information is known and frozen. But store it all in one place and keep it up to date.
  • Get feedback on your documentation too - both as a health check and for clarity and comprehensiveness - and incorporate it. One of the best ways to do this is Jason Freedman’s 30/90 feedback method. At 30% completion, ask a reviewer to look at the broad outline, flow, and structure of document. At 90% have them go over it with a fine-toothed comb. Have peer, user and expert sessions in between.

Full post here, 6 mins read