From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FyFRh-0004S4-Im for qemu-devel@nongnu.org; Wed, 05 Jul 2006 18:02:09 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FyFRg-0004Qj-2Q for qemu-devel@nongnu.org; Wed, 05 Jul 2006 18:02:08 -0400 Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FyFRf-0004Qg-Ro for qemu-devel@nongnu.org; Wed, 05 Jul 2006 18:02:07 -0400 Received: from [83.148.189.24] (helo=mxbackup.griffin.com) by monty-python.gnu.org with esmtp (Exim 4.52) id 1FyFRi-0006ll-My for qemu-devel@nongnu.org; Wed, 05 Jul 2006 18:02:10 -0400 Received: from Agape.local (82.151.249.90.adsl.griffin.net.uk [82.151.249.90]) by mxbackup.griffin.com (Postfix) with ESMTP id 929C210E8BD8 for ; Wed, 5 Jul 2006 23:02:06 +0100 (BST) Subject: Re: [Qemu-devel] No useful documentation. From: Daniel Carrera In-Reply-To: <20060705214643.GB21797@muon.de> References: <1152133046.8295.85.camel@Agape-desktop> <3621.12.168.72.168.1152135247.squirrel@12.168.72.168> <1152134568.8295.97.camel@Agape-desktop> <20060705214643.GB21797@muon.de> Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="=-SWef/1jabrqzVVe0ogRL" Date: Wed, 05 Jul 2006 23:01:59 +0100 Message-Id: <1152136920.8295.126.camel@Agape-desktop> Mime-Version: 1.0 Reply-To: daniel.carrera@zmsl.com, qemu-devel@nongnu.org List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org --=-SWef/1jabrqzVVe0ogRL Content-Type: text/plain Content-Transfer-Encoding: quoted-printable On Wed, 2006-05-07 at 23:46 +0200, Udo 'Robos' Puetz wrote: > __Straight from the docs__ >=20 > -hda file > -hdb file=20 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) doc= s > 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. --=20 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 --=-SWef/1jabrqzVVe0ogRL Content-Type: application/pgp-signature; name=signature.asc Content-Description: This is a digitally signed message part -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.2.2 (GNU/Linux) iD8DBQBErDbXp0IZBOPRtlQRAjQxAKCOz/bIZmvqIGX1mbI5hqpN+eSVzwCfeI0b BLeuC1Wof+/sh2Sus6JRo14= =5GOw -----END PGP SIGNATURE----- --=-SWef/1jabrqzVVe0ogRL--