Am Samstag, 7. März 2015, 13:47:44 schrieb Norman Feske:
Hi Norman,
Hi Stephan,
My experience with such documentation (considering that I am maintaining a 1500+ design documentation of the Linux kernel) is that references to the code are helpful. For example: when you talk about a capability in section 3.1, just add a hint which C++ object such capability is stored in. With this, a reader now as an entry into the code and can start to understand the code.
Note, I am not looking for comprehensive code snippets -- just a reference to the code structs / objects.
that is a good advice. I actually deliberately tried to keep Chapter 3 void of "implementation smell" to avoid distracting the reader from understanding the architectural concepts. But I agree that the reader might desire to the draw the connection to the actual code.
Would the addition of cross references to the corresponding subsections of Chapter 7 (Functional specification) achieve the desired effect? Chapter 7 will contain the actual API documentation (of course referring to the source code). This way, the text in Chapter 3 would not directly but indirectly refer to the source code.
That would be equally good. The only thing I would recommend to avoid is a design documentation that lacks the link to the actual code.
Best regards Norman