Documentation - request for feedback

[Norman Feske]

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
Norman

-- 
Dr.-Ing. Norman Feske
Genode Labs

http://www.genode-labs.com · http://genode.org

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