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 ------------------------------------------------------------------------------ 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
