Hi folks, When a book has more than one index, the contents of the indices are almost always disjunct.
If there's an "Index of music examples" and a "Subject index" in the same book, then the items listed in the first index will almost never appear in the second index, and vice versa. NR-D (LilyPond command index) and NR-E (LilyPond index) violate this. Correct me I'm misunderstanding, but it certainly appears that the contents of NR-D and NR-E overlap entirely: NR-D indexes ~1500 LilyPond commands; NR-E then indexes these exact same ~1500 commands, together with additional information. Not only are NR-D and NR-E not disjunct, NR-D appears to be fully included in NR-E. The problem here isn't just that this violates the usual expectations for what a book is, though there's that. The problem is that the duplication of content between NR-D and NR-E takes a toll on the usability of the docs for many readers. Christopher and Simon talked about this in April ... https://lists.gnu.org/archive/html/lilypond-devel/2024-04/msg00027.html ... but the discussion missed the fact that the reason Christopher was confused is because we're violating the norms of how indices are supposed to work in the first place. SUGGESTION #1: Remove NR-D "LilyPond command index" entirely, in favor of NR-E "LilyPond index." I realize it may sound alarming to lob off an entire index from the docs, but please click back and forth between NR-D and NR-E for a moment and verify for yourself that NR-D is serving no actual purpose: all the commands in NR-D are already listed in NR-E. Not only that, but so long as NR-D and NR-E both continue to exist, every time a user wants to look something up in the indices, she or he is faced by a potential flicker of hesitation: Which index? How do I know? If I consult only one index, am I missing valuable references in the other index? And so on. This is a real toll on usability, and this is why actual print books separate out the contents of different indices, precisely to avoid this type of confusion on the part of readers. You can see this hesitation immediately if you watch users (especially new users) interact with the docs. SUGGESTION #2: Promote the remaining "LilyPond index" up and out of the section of appendices in the NR table-of-contents, conforming to how actual print books work. Taken together, these suggestions will change ... *AppendicesA. Notation manual tablesB. Cheat sheetC. GNU Free Documentation LicenseD. LilyPond command index E. LilyPond index* ... to ... *Appendices* *A. Notation manual tablesB. Cheat sheetC. GNU Free Documentation LicenseLilyPond index* ... instead. It would be nice to see these changes in 2.26. If any more convincing is necessary, I urge developers to think through the user experience of making a choice between indices with redundant contents (as I sketched above) and then to leaf through the front- or backmatter of an actual print book. -- Trevor Bača www.trevorbaca.com soundcloud.com/trevorbaca
