Re: [Qemu-devel] No useful documentation.

[Daniel Carrera]

On Wed, 2006-05-07 at 23:46 +0200, Udo 'Robos' Puetz wrote:
> __Straight from the docs__
> 
> -hda file
> -hdb file 

Yes, but the doc doesn't, for example, explain how you are supposed to
put a bootable image in "file". This is addressed by the excellent
responses from Nathaniel and Rick, and I included it in my proposed
tutorial.

This is the sort of thing that might be obvious to you in hindsight
(you're very involved in qemu) but won't be to a lot of people who are
technically competent, but don't already know qemu.

> I *guess* you, daniel, would have liked something where you had it all
> pre-chewed so that you don't have to read.

If what you mean is "good documentation", yes, that would be nice. Feel
free to use my proposed tutorial, I would be flattered if you did. And
yes, I do know a couple of things about documentation. Good
documentation gives clear steps and doesn't leave important things
unexplained. Step-by-step procedures, even if they don't exactly match
the reader's use case (but can be generalized), are a good idea.


> Some other people said it before in other contexts, I repeat it for qemu:
> it isn't free, you have to pay by reading stuff (short version)

That's a very sad attitude. That's not the attitude that I took when I
wrote the user guide for OpenOffice.org (http://oooauthors.org). I took
the attitude that documentation is critically important and that to
serve its role well one has to put a strong focus on clarity and
explanation. It is tempting to simply list all the features that a
program has. But a feature-based documentation is mostly useful as a
reference. That is, something you use once you have the mechanism down.
It is critically important to write task-based documentation. In other
words, ask "what does the user want to do?" and write down how to do it.

> If you become agitated because some docs are (in your opinion) bad, think
> about what you "paid" for it and - in my case - I still see the (bad) docs
> but keep myself from insulting people who work for free and in their free 
> time!!

I have spent a lot of time working for free on my free time, so I know
the feeling. I still say that making things difficult and calling it
"payment" is not a good attitude. Other people in this list took the
approach of helping solve a problem and in turn I suggested a tutorial
that would cover this situation.

Cheers,
Daniel.
-- 
http://opendocumentfellowship.org
  "The reasonable man adapts himself to the world; the
  unreasonable man tries to adapt the world to himself.
  Therefore all progress depends on unreasonable men."
        -- George Bernard Shaw

signature.asc
Description: This is a digitally signed message part