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
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
I've just started reading the documentation and have noticed some very, very minor issues (most are just stylistic and not real errors). Would you be interested in me noting them for you? example of a very minor improvement: p16. s3.1.3 l5 : "puts the function arguments to a place" => "transfers (or copies?) the function arguments to a place" | "puts the function arguments in a place" : the issue here is that "to" doesn't sound right with "puts", also "puts" is usually discouraged if you can use a more descriptive word such as "transfers". ross mcginnis
Hello Ross,
I've just started reading the documentation and have noticed some very, very minor issues (most are just stylistic and not real errors). Would you be interested in me noting them for you?
yes, of course. Style improvements are very much appreciated!
Thank you Norman
-
Norman Feske -
ross mcginnis -
Stephan Mueller