Documentation, was: [Re: Questions about copy-on-write]

[Rian Hunter]

Sam Mason wrote:

> I've had another read of the documentation and it's proving to
> be *very* hard going - sorry to the authors!  I'll see if I can
> rewrite it so it makes sense to me.  It's basically the paragraphs
> following the start of the "Containers" section up until the "The
> Container Interface" subsection.
>  
If the documentation (hurd-on-l4.tex) looks confusing to you, and you're 
struggling to understand it, I usually find it easier to wait for a 
beginning implementation and then following the code. If you don't have 
much experience with VM, L4, IPC security, or even microkernel methods 
and constraints it will be very hard to follow in one sitting.

So if you are trying to understand how HURD-L4 works, you also have to 
realize that the documentation isn't dogma and ideas are still being 
intensely examined and straightened out. To me at least, it would be 
better to get just a general understanding of how it works and see how 
the author actually implements this to see and understand all the 
nitty-gritty details, then comment or patch that code or ask questions 
about why it does this or why it does that.

A good example is the current capability library. Since it isn't very 
complicated, it's much easier to browse through and actually see what is 
going on than trying to work out a new implementation in your head from 
the description.

What i'm trying to say is that it seems to me that the best way to 
understand software is to simultaneously look at the 
documentation/comments and code to find incongruencies or clarifications.

**DISCLAIMER** I am not promoting not reading the documentation. I am 
not promoting not thinking of better or newer implementations. I am not 
saying that the author of the documentation (Marcus) should do all the 
beginning work.

thanks
-rian