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 ------------------------------------------------------------------------------ Dive into the World of Parallel Programming The Go Parallel Website, sponsored by Intel and developed in partnership with Slashdot Media, is your hub for all things parallel software development, from weekly thought leadership blogs to news, videos, case studies, tutorials and more. Take a look and join the conversation now. http://goparallel.sourceforge.net/ _______________________________________________ genode-main mailing list genode-main@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/genode-main
