DEV Community

Discussion on: What are your best practices for writing documentation?

Collapse
 
bgadrian profile image
Adrian B.G.

Except for the user manual, I had to keep, a minimal doc of type:

  • high level, of how things work at a very abstract level, describing the business problem and 10000 feet implementation - keep it simple and use images, can be replaced by the actual task description.

  • user manual - the users of the system, is like a Help, this is the most difficult to keep it up to date, and usually requires copywriters that are kept in the development loop. For non-technical people so avoid buzzwords and technical details.

  • technical docs - how systems works, where are they hosted, how to make a local setup, data/user flow diagrams, what algorithms are used, what techniques and so on, configs, APIs documentation. This can be understood by any engineer/QA/lead/architect.
    The trick here was to update it each sprint, I usually done this while the task was at QA and I had downtime. They have to be related to tasks (2way links) so best place for them was in the project management software/wiki.

  • developer only - usually code comments, automatic tests, classes diagrams.
    This were pretty much done as going, keeping them in the project or some in wiki.