Re: should we have a new 'tools' manual?

From: "Daniel P. Berrangé" <berrange@redhat.com>
To: Peter Maydell <peter.maydell@linaro.org>
Cc: Paolo Bonzini <pbonzini@redhat.com>,
	QEMU Developers <qemu-devel@nongnu.org>,
	Stefan Hajnoczi <stefanha@redhat.com>,
	"Dr. David Alan Gilbert" <dgilbert@redhat.com>
Subject: Re: should we have a new 'tools' manual?
Date: Fri, 7 Feb 2020 11:59:52 +0000	[thread overview]
Message-ID: <20200207115952.GB2511885@redhat.com> (raw)
In-Reply-To: <CAFEAcA--P9FLM4qBxf23sLuv5Tz4HRgj7ONC7ODxnfZiLph9TA@mail.gmail.com>

On Fri, Feb 07, 2020 at 11:50:37AM +0000, Peter Maydell wrote:
> So far we've been converting docs to Sphinx and assigning them
> to manuals according to the division originally set out by
> Paolo on the wiki: https://wiki.qemu.org/Features/Documentation
> 
>  * QEMU User-mode Emulation User's Guide (docs/user)
>  * QEMU System Emulation User's Guide (docs/system)
>  * QEMU System Emulation Management and Interoperability Guide (docs/interop)
>  * QEMU System Emulation Guest Hardware Specifications (docs/specs)
>  * QEMU Developer's Guide (docs/devel, not shipped to end-users)
> 
> but some of our documentation has always been a bit of an awkward
> fit into this classification:
>  * qemu-img
>  * qemu-nbd
>  * virtfs-proxy-helper
> etc. I've tended to put these things into interop/.
> 
> The proposal from Dan and David was that we should add a sixth
> top-level manual
>  * QEMU Tools Guide (docs/tools)
> 
> which would be a more coherent place for these to live.
> 
> This seems like a good idea to me -- do people agree? What's
> our definition of a "tool", or do we just know one when we see it?
> What in particular should go in tools/ ?

There are essentially two consumers of our docs

  - Sysadmins running / interacting with QEMU
  - Application developers building QEMU mgmt tools

In the sysadmin use case, they'll primarily care about docs describing
the system emulator configuration & usage, and the various tools usage.

The app devs will care about nearly all of our documentation, except for
stuff that is purely QEMU internals.

The downside of mixing tools into the general "interop" doc is that it
makes it harder to find IMHO. Thus having a dedicated "tools" doc will
be a useful grouping for sysadmins to quickly find docs relevant to
daily admin tasks.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|