Re: [Qemu-devel] KVM call agenda for April 05

[Stefan Hajnoczi <stefanha@gmail.com>]

On Tue, Apr 5, 2011 at 1:21 PM, Brad Hards <bradh@frogmouth.net> wrote:
> On Tue, 5 Apr 2011 06:29:48 pm Alexander Graf wrote:
>> > quality and resubmission. It would also help to have some explanatory
>> > text for some of the architectural docs that are available (e.g. there
>> > is a lot of words on the wiki about QED, and I guess its some kind of
>> > storage / disk thing, but I have no idea why its important, or even if I
>> > should know about it).
>>
>> Take a look at http://wiki.qemu.org/Contribute/StartHere. It links to
>> (rudimentary) explanations for QED. We don't have a full-on architectural
>> doc though. And I'm not sure we ever will - unless people volunteer to
>> write documentation instead of code :).
> I take it you meant http://wiki.qemu.org/Features/QED (and the pages that link
> from there). I still don't know what QED does. I'm guessing something related
> to block devices (blocks get mentioned) and it is different to something called
> "raw", but I still don't know what QED does (or does differently / better than
> something else).

QED is an image format.  Like qcow2, vmdk, vpc, vdi, and others.

> There is detail on why things are the way they are, but no context to help
> situate that detail.
>
> The problem isn't with QED in particular. That is just an example of the issue
> - it could be applied equally to sheepdog, or VNC / Splice / SDL display, or
> some of the other things I don't even know that I don't know.
>
> I personally found the qdev presentation style pretty approachable:
>  - here is how it used to be...
>  - that sucks for all the obvious reasons, and some you didn't think about...
>  - here is how we do it now / should do it...
>  - that sucks (less) for these reasons...
>  - here is what you should do...
>
> That isn't going to replace reading the code and copying examples. There
> should only be enough detail to tell people "you should know X and Y, and look
> here for more".

This stems from the fact that development is centered around the
mailing list.  Some folks have put technical documentation on the wiki
but a lot simply happens on the mailing list.

Once the discussions have finished and code is merged the people
involved have that knowledge but I agree that it isn't easy for
newcomers to gain that knowledge.  Searching mailing list archives
should help you get that knowledge but it's more tedious than an
organized wiki.

I'm unsure how we can sustainably keep the wiki up-to-date on detailed
code internals knowledge.  Any suggestions, any examples of projects
doing this successfully?

Stefan