Documentation - request for feedback

[Stephan Mueller]

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


-- 
Ciao
Stephan