How can I create well-structured documentation that is easy to read and provides background information for the audience? What strategies or methodologies can help ensure clarity and accessibility?
Is there a good template that works 100% of time ?
I've written thousands of lines of code of payments related code for a high-traffic financial company (with a few attempts earlier in my career to actively "document" code) and the best way I found to document my code was to:
What generally needs documention for me though is the high-level of a feature or a product. High level behavior is less susceptible to change and is harder to understand (since it's built from many layers of code), so documentation is more valuable here (it grows stale slower & the information exposed is time-intensive to get). A good eng design doc will do the job here: bonus points if an engineer links the design doc in every commit/PR to implement that design doc.
To add to above question:
How do I determine what content is essential to include in the documentation, especially when unsure of the audience’s background knowledge? What strategies can help assess the right level of detail without overwhelming the audience?