Documentation - request for feedback

Norman Feske norman.feske at ...1...
Sat Mar 7 13:47:44 CET 2015

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.

Best regards

Dr.-Ing. Norman Feske
Genode Labs ·

Genode Labs GmbH · Amtsgericht Dresden · HRB 28424 · Sitz Dresden
Geschäftsführer: Dr.-Ing. Norman Feske, Christian Helmuth

More information about the users mailing list