[b112]

Qemu is great, the DEVs and all who worked on her deserve applause, except for documentation. It's like someone creating a huge Japanese titanium indestructible fighting robot, but then using aluminum in the feet/heels.

So much of my qemu work spent on randomly changing options, with no change documentation, discovering features, with no documentation, options with no reason or indication why, manpages out of date, READMEs not updated, changelog not there, etc.

[bonzini]

Documentation is not great I admit. The problem is that we don't have anyone who is a capable tech writer in the team. It's not something that you can improvise.

However, all incompatible changes are documented and also announced at least 8 months in advance.

https://www.qemu.org/docs/master/about/removed-features.html

https://www.qemu.org/docs/master/about/deprecated.html

It may seem like there are many, but in practice they are in very old, mostly unused or very badly designed corners. For example configuration of audio was overhauled last year, and is now the same as basically all other backends (e.g. -audio pa,model=sb16; compare with -nic user,model=e1000 for a network card).

[justinclift]

As a general thought, would it be possible to put out a "call for tech writers" post or similar on the front of the qemu website, or even a prominent blog post in the blog section?

[bonzini]

Yes, I guess it would be an idea. We could also participate to Season of Docs.

[dev-n]

bonzini I'm a QEMU fan ... and a techwriter. Is there a way to send you an email? There's no real contact option on qemu, other than IRC.

[guerby]

Paolo Bonzini email is available here:

https://github.com/qemu/qemu/blob/master/MAINTAINERS#L134

[justinclift]

Stable url: https://github.com/qemu/qemu/blob/cec99171931ea79215c79661d3...

[bonzini]

[e-mail] :) thanks very much!

[justinclift]

Sounds like it'd be a useful avenue for closing a major (non-code) problem with the software. :)

[cedws]

Agreed, the CLI in particular is a complete mess.

[bonzini]

If there are parts that specifically you'd want to have better documentation for, please let me know here.

Generally we've been moving command line towards a scheme where each option describes an aspect of either the guest (a device, the board type, the CPU model) or the interface to the host (a file holding the contents of the disk, the network bridge to attach to, how to show graphic contents), with some options providing both as a shortcut (for example -nic, -audio, -serial).