Re: [PATCH 1/1] docs/qapi-domain: Improve QAPI indices

[Markus Armbruster <armbru@redhat.com>]

I refreshed my memory on this.  It's been a while.  Instead of replying
to your replies long after you wrote them, I'm going to write up my
thoughts in one place.


= General observations =

* We have three QAPI-generated manuals: QEMU QMP Reference Manual, QEMU
  Storage Daemon QMP Reference Manual, QEMU Guest Agent Protocol
  Reference.

* We generate an index for each manual: qapi-qmp-index.html,
  qapi-qst-index.html, qapi-qga-index.html.

* The doc generator does not link to these indexes by itself.  Instead,
  each manual links to its index in its introduction section.  This
  makes the index really easy to miss.  Even if you're aware, jumping to
  the index is bothersome once this lone link is out of sight.  Until
  that changes, the practical value of improvements to the index is in
  doubt.  Doesn't mean improvements should not be made, only that they
  better be cheap.

* You're proposing to additionally generate a "main" QAPI index
  qapi-index.html for everything documented in any QAPI-generated
  manual.  Not linked from anywhere.

* Modules let developers structure the schema and the generated code.
  They are not a thing at the QMP interface.  Letting such internals
  bleed into QMP documentation is *wrong*.  The excuse for doing it
  anyway is that the module tree is close to the section tree in
  practice, and we can use the modules (which are readily available in
  the doc generator) as an approximation for sections (which we don't
  have there at this time).


= Indexes before the patch =

An index page starts with links

    Alternates | Commands | Enums | Events | Modules | Objects | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z 

Then we have flat lists of the alternates, commands, enums, events,
modules, objects, entities starting with "A" or "a", ..., "Z" or "z".
Each list is alphabetically sorted.

The links at the top take you to the heading of the respective list.

The list entries link to entity documentation, except for "Modules",
which link to the beginning of the doc generated for a QAPI module.
The entries under "A", ..., "Z" have a (meta-type) suffix.

Every entity is listed twice, once under its meta-type (Alternates,
Commands, Enums, Events, Objects), and once under its first letter.


= Indexes after the patch =

An index page starts with links

    By module | By type | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

Then a two level list module / entity name (meta-type) linking to the
entity's doc.  Link "By module" takes you to its heading.

Then a two level list meta-type / entity name linking to the entity's
doc.  Link "By type" takes you to its heading.  This replaces the flat
lists Alternates, Commands, Enums, Events, Objects.

In both two level lists the outer level is collapsible.

Then flat lists "A", ..., "Z" as before.

Flat list "Modules" is gone.

The links at the top take you to the heading of the respective list.

Every entity is listed twice, once under its meta-type under "By type",
and once under its first letter.

The lists are now sorted case-insensitively.


= Critique =

Here's the one question that matters: what are readers trying to do when
they use the index page?

Assuming they find the index page in the first place (see "lone link"
under "General observations" above), but that issue is out of scope
here.

I believe readers use the index to jump to the doc for X, where X is
something they encountered in the QMP interface.

I don't think they'll use the index to jump to the doc of an Y they
encounter in documentation, because that Y will be a link.

X obviously includes commands and events.

I doubt it includes types.  Type names are not a thing in the QMP
interface.  You run into them only in documentation, but again, they are
links there.

We should make looking up a command / event as easy and quick as we can.

Let's examine how users can navigate to the index entry that takes them
to the command / event doc.

Before the patch:

1. Find the index page somehow (out of scope here).

2. Click on Commands / Events.  For commands, can instead visually skip
   over the alternates (which is just a few lines) to Commands.

3. Visually scan an alphabetically sorted list of ~250 commands (almost
   seven screen-fulls for me) or ~50 events (a bit over one).

Alternatively:

2. Click on the letter the command / event starts with.

3. Visually scan an alphabetically sorted list of up to ~200 entries
   (five screen-fulls for me).

Alternatively:

2. Have the browser search the index page for the name.

Alternatively:

1. Screw the index, search the entire manual (single page) for the name.

After the patch:

1. Same.

2. Click on "By type".  If you can somehow divine that's where the
   commands / events hide.

3. For commands, visually skip over the alternates (which is just a few
   lines) to Command (could also collapse Alternate, but why bother).

   For events, either scroll down a lot looking for the events, or
   search for "event" (for me, that jumps right back to the top of the
   page to show me the first event under "By modules").  Could also
   collapse Alternate, Command, and Enum, but most likely just give up
   and try an alternative.

4. As before, visually scan an alphabetically sorted list of ~250
   commands (almost seven screen-fulls for me) or ~50 events (a bit over
   one).

The alternatives are unaffected by the patch.

I'm afraid the patch makes the index harder to use.

Minor quibbles:

* The "type" in "By type" is wrong.  It's by QAPI meta-type, which is
  not the same as QAPI type.  Casual readers will likely not be familiar
  with the term "meta-type".  Calling the thing type risks confusion
  nevertheless.

* The Modules sub-index before the patch is useless.  The navigation bar
  on the left is much, much easier to use.  It also shows the *actual*
  section structure, not an approximation.

* The "By Modules" index after the patch is debatable.

* I can't see a use for the "main" QAPI index.


= Recommendations =

* Consider dropping types from the index entirely.  This would make
  navigating to commands and events via first letter links *much*
  easier.  No need for Commands and Events lists, the "A", ..., "Z"
  suffice.

* Else, keep an obvious, one click path from top of index page to
  commands and to events.

  However, the list of commands is too long to quickly scan visually.
  Consider breaking it up by first letter.

* Keep the switch to case-insensitive sorting.

* Definitely drop the Modules sub-index.  I don't care for the "By
  modules" thing, either.  The navigation bar on the left does that job
  better.

* Drop the "main" QAPI index.

* Out of scope for this patch: a manual's index page should be easy to
  reach from anywhere in the manual.


Thoughts?