Here’s what I found while reading a comment by Bill de hOra on a lesscode article on writing documentation by Richard Dyce:
lesscode article on writing documentation
I opened it up and found a print-out provided from a CASE tool. It showed a few diagrams, and gave exhaustive descriptions of every class, with every attribute, and every operation. [...] There was much on what the objects were, but little explanation of what they were meant to do. [...] The idea is that a graphical object model can show how objects fit together more clearly than looking at the source, an interaction diagram can show a collaboration better than figuring out the call path from several class definitions. [...] CASE tools encourage a dictionary mentality. You make an entry for every class, you show every class and every attribute on the diagrams, you draw an interaction diagram for every use case. They encourage completism by helping you answer the question “have we documented everything?” — Martin Fowler ¹
That reminds me of that one idiot architecture astronaut I met on the job wanting state diagrams for all the classes. I said something about concentrating on the narrative level, explaining the important parts and how they interact. No, he wanted state diagrams for *all* the classes.
The documentation for system Y on the other hand, was the work of a master craftsman. A craftsman whose craft is software engineering. In the space of 5 information packed pages he succeeded in telling me the things I really needed to know about System Y. The things that no amount of looking at the data structures or the code itself would tell me. In short, it was real documentation. Real words put together by a real person adding real value over and above what any ’report’ would tell me. It was an authored document, not a generated one. That made all the difference. – Sean Mc Grath ²
I need to write this kind of documentation for Oddmuse! 😄
#Software