On 21/12/2010, at 10:15 PM, Anthony Davis wrote:

Hi Justin,

I can offer some free time :)

Awesome Anthony, very welcome. :) There's a pretty broad spectrum of things we need to get improved. :)

From stuff that doesn't take any real virtualisation knowledge:

+ The new Virsh Command Reference. Most pages just list the command name and the version of libvirt it came in, without even showing the arguments the command can be given. Like this: http://libvirt.org/sources/virshcmdref/html/sect-list.html It just needs someone(s) who can run the virsh "help" command for a command, and then write down the options the command has. We're using a really simple text format for this, so it's pretty easy. :) Stuff that requires knowledge of an operating system, but not necessarily deep Virtualisation knowledge: + The existing docs on the libvirt.org website have been (mostly) written by people using path names that apply to Fedora and RHEL. It would be good to identify these, and update these to include the correct paths for other Linux distributions too, such as Ubuntu, OpenSUSE, Gentoo, and so on. Probably the first thing that needs to be done for this is just someone to scan through the pages on the website making a list of which ones have paths to be looked at. We can then figure out from there what it'll take, who needs to do what, etc. :) + Screenshots. Lots of the virt-manager pieces and processes could benefit from having good screenshots taken to show the process. Note, I haven't really thought this bit through to a deep level, so we probably need to discuss, make a list, and so on. :) Stuff that could really use a person that *does* have solid knowledge about some aspect of things, or a strong desire to learn it (then write it up). The two areas that jump out the most as needing attention here are: + Virtualisation storage concepts. There are some initial bits around "What is a storage pool? What is a storage volume? How do we use them?" in places, but nothing really nicely put together, targeted to general SysAdmin users. Some of this info does exist in the Fedora or RHEL virtualisation guides, but they're distro specific and this info should be available on the libvirt.org or virt-tools.org websites themselves. + Networking and virtualisation. All kinds of stuff here, from explaining how each of the virtual networking types work, through to explaining what the VirtIO network device is, and how to install the drivers for it in Windows. All of which is directly of use to heaps of people, and hasn't yet been written. Heh. ;) So, I guess the first and best question is "which of the above sounds like you?" :) Regards and best wishes, Justin Clift

On 22/12/2010, at 3:23 AM, Scott Baker wrote:

On 12/21/2010 03:15 AM, Anthony Davis wrote:

...

Hi Justin,

I can offer some free time:)

I'd be willing to contribute to a wiki if we had the docs in a wiki.

Yeah I know what you mean. Wiki's are *so* much easier to work with and revise, compared to having to code in html then submit diffs as patches. At the moment, the "main" libvirt docs are written in html and included with each release tarball. It makes sure everyone who downloads the tarball has a copy, but it doesn't make them easy to edit. :/ Some of the things that need documenting though, are definitely able to be written up into a wiki first to get them into shape. We could then move the things that are "finished" in the wiki to the main tarball (after converting to html). I personally do similar to this anyway for lots of things, as I find getting info onto a wiki first allows me to refine, refine, refine, until I'm happy with it. Then it can go anywhere. This is the first tentative Docs Team To Do list page (on the wiki even), just whipped up using the contents of a reply to Anthony: http://wiki.libvirt.org/page/DocsToDo Stuff that I reckon would be suitable for writing on the wiki generally fall into the second and third categories there, of things that need either some OS level knowledge (for investigating non Fedora-RHEL paths), or for writing up concepts around Storage, Networking, or similar. You up for it? :) Regards and best wishes, Justin Clift

On 21/12/2010, at 10:32 PM, Zdenek Styblik wrote:

Hello Justin,

could you be more specific, please? How to put it. Your e-mail is too ambiguous for me :)

Heh, no worries. I often talk in general terms first. :) The email response to Anthony, sent a few minutes ago, has more detail. I know there's a lot of demand for better documentation in libvirt, and other Open Source projects around have gotten together teams/groups of people who's main mission is to improving their documentation/manuals/learning materials (and so on). So, I reckon we see about doing the same thing for libvirt. Looks like there are people willing to pitch in, so I guess it's now a matter of figuring out what needs to be done, who's interested in doing what, and so on. If we need a libvirt-docs mailing list too, that can be done without too much effort, but not sure it's needed just yet. (open to suggestions :)) Hmmm, that email reply to Anthony should probably be copied to the wiki and we can expand on it from there. :) Is this the kind of detail you're after Zdenek? Regards and best wishes, Justin Clift

On 22/12/2010, at 6:50 PM, Zdenek Styblik wrote:

As for documentation in HTML. How about to write parser which would download pages from wiki, cut eg. menu, footer => garbage off, and replace it with whatever you want and like? I have to say I haven't seen documentation shipped with libvirt [heh?! :) ], but since you say it's HTML and Wiki output *is* HTML ... hm? Just an idea.

Heh, interesting thought, but really not sure how workable that is. *So* far when I've been transferring things from the wiki to the (basic) HTML format, I always seem to tweak things or slightly re-arrange them on the way through. I kind of feel this human step of editing is nice to have. But yeah, there is something to be said for efficient automated approaches too. :) With the libvirt documentation, it's actually the libvirt.org website (thus the html). The entire website is the "docs" subdirectory in the tarball release. So, anyone that installs from tarball has the full website. (I think it's kind of unusual, but other people seem to like it. Heh.)