Documentation - request for feedback

[Stephan Mueller]

Am Freitag, 6. März 2015, 16:22:16 schrieb Norman Feske:

Hi Norman,

>Hello,
>
>according to our road map (http://genode.org/about/road-map), the
>upcoming Genode version 15.05 will be accompanied with comprehensive
>documentation. The work on this documentation is in full swing and can
>be tracked at the corresponding Git repository:
>
>  https://github.com/nfeske/genode-manual
>
>A snapshot of the current version is available as PDF at:
>
>
>http://genode.org/files/53bcb8e33fe6602fed25edc3c7b922c5/manual-2015-03
>-06.pdf
>
>So far, the work on the following chapters is completed already:
>
>  3. Architecture
>  4. Components
>  6. System configuration
>  8. Under the hood
>
>I would greatly appreciate feedback from the community about those
>chapters - be it in the form of minor spelling or grammar fixes,
>suggestions for additional topics you wish to see covered, hints about
>misleading paragraphs, or any other concerns that you may have.
>

This is really great to see such comprehensive documentation!

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.

>Cheers
>Norman


Ciao
Stephan
-- 
| Nimm das Recht weg -                                             |
|  was ist dann der Staat noch anderes als eine große Räuberbande? |