this is a great summary. I also like to add proper information about the context, the required knowledge to tackle each part, and the goal of that part of the d

this is a great summary. I also like to add proper information about the context, the required knowledge to tackle each part, and the goal of that part of the documentation itself. in most cases, you can write a couple lines at the start of a document saying: "this document explains A. you will be interested on it if B. you should already know about C and D before proceeding. otherwise, you might be interested on E or F instead." I also noticed an interesting situation when trying to write good documentation: if you start too early, you will have to update it and change it a billion times (both writing the docs and testing the systems will reveal a lot of parts that can be improved). but if you start too late, everything will seem to be ok until you try to write it down. when you have done a few high-level overviews and detailed technical references, that always reveals how the are a number of important parts that could be simpler and/or more harmonic. we always try to make code simpler, but sometimes we only discover simpler ways to express things when we are thinking about them in natural language. or the other way around. perspective++