My own approach to describing what the code does is quite terse. I prefer the code to speak, and layer it in such a fashion that the reader is able to see the big picture and venture deeper inside the routines to see more. Furthermore, easily readable tests are excellent documentation with the bonus that they are practically always up-to-date. Sadly, this is not always achieved and therefore some documentation is usually necessary.
Concerning large systems there should be several levels of diagrams and explanation of concepts. These levels should be layered such that one can get a high-level overview of the technical things and descend downwards to graps the details. Documenting exhaustively is often very difficult and choosing the few key areas to document is important. The high-level view can be presented with a component diagram and the lower levels start to include more class diagrams. Sequence diagrams are often a great way to explain the interconnections and timing of requests of the systems' different components.
On a lower level, I find it important to describe the design decisions, why things were made the way they are, what were the constraints and what kind of matters were considered. These are the things which are hard to deduce from the code and APIs. The favorite question of everyone seems to be "Why was this made this way?" and I strive to answer exactly that in documents.
While writing end-user documentation I prefer to make a quick overview and then show some good examples of the most common uses of the program, and after that describe the usage in more detail. An example can be found in the JS form dependency library I've authored.
The level of documentation often depends on the project and I have also produced documentation much more abundantly than I discuss here.
Concerning large systems there should be several levels of diagrams and explanation of concepts. These levels should be layered such that one can get a high-level overview of the technical things and descend downwards to graps the details. Documenting exhaustively is often very difficult and choosing the few key areas to document is important. The high-level view can be presented with a component diagram and the lower levels start to include more class diagrams. Sequence diagrams are often a great way to explain the interconnections and timing of requests of the systems' different components.
On a lower level, I find it important to describe the design decisions, why things were made the way they are, what were the constraints and what kind of matters were considered. These are the things which are hard to deduce from the code and APIs. The favorite question of everyone seems to be "Why was this made this way?" and I strive to answer exactly that in documents.
While writing end-user documentation I prefer to make a quick overview and then show some good examples of the most common uses of the program, and after that describe the usage in more detail. An example can be found in the JS form dependency library I've authored.
The level of documentation often depends on the project and I have also produced documentation much more abundantly than I discuss here.
