Excellence in documentation presumes a certain accuracy and relevancy, a certain consistency and totality, and certainly other impressive words that end with 'y'. But all of that doesn't help User if they can't find what they are looking for.
Inability for User to find what they are looking for chips away at "perceived quality" - that nebulous aspect of quality that, despite its unquantifiable nature, can't really be ignored. Indeed, the scorn "this product (or documentation) sucks" can simply be born out of User's inability to find what they are looking for. So, not that the deliverable doesn't have it, but User couldn't find it, or worse, User didn't even know it existed.
**Bold, contentiousness statement alert**: Of all the navigation features you can integrate into technical documentation (table of contents, search capability, breadcrumbs), none is more powerful in delivering User to where they need to be than the Index.
Bane of authors, boon of User, the index is an information product within an information product - tipping off User that there is more to know than what they set off to find.
So then.. why is it that fewer and fewer publications that should be indexed aren't, while at the same time Indexing became a sought after, credentialed profession? Do indexes help User or not? Our users thought so when we asked them; in fact, not many words were minced: The index in the SQL Anywhere documentation - useful to you?
Wanting to be sure it wasn't just personal opinion-based (albeit shared by many persons), I decided to take a look at how others in the publishing industry addressed the same question. In my travels, I spotted a study that bothered to look at the question empirically.
The Bloomberg BNA Study
Bloomberg BNA is a leading expert in, and source for, legal, tax, regulatory and business information. They had the same question about the value of indexes and set out to investigate by conducting a study. They found definitive benefits from indexing for certain types of documentation. If you don't have time to read the PDF, you can also watch their cool YouTube presentation: Indexes and the Google Generation -- What You Don't Know Will Hurt You - presented by BNA. I got pretty deeply engrossed around minute 14, tho you may want to understand a bit about what the test groups were required to do to understand the usefulness of the findings (i.e., start watching from the beginning).
The stats I liked best were: Search users had an over 23% success rate at finding a complete answer to their question, while Index users had an 86% success rate. OK. Wow :smile:
Of course, our users were trying to tell us the same thing in their feedback, but it's helpful to see it from the perspective of other industries (legal, in this case), and to see some numbers around findings.
Incidentally, I found out about the Bloomberg BNA study while exploring Leverage Technogies' website. Leverage Technologies offers "Consulting, Publishing/Indexing Software, Custom Programming, and Production Services for the Publishing Industry", and it's clear they see the value of indexes in publishing. Their website offers a helpful PDF from the BNA Law School Education Series summarizing the study and the benefits of indexes, and suggest some risks of not providing them. They also go on to give guidance on index creation (Why Create Indexes for Publications) as well as how indexes address gaps that text searching can introduce (Indexes versus Searching in Publications).
While exploring around, I found the webpage for the Publishing Technology Group of the Society of Indexers in the UK. They give a nice summary of when text searching is ideal vs. index searching.
I strongly encourage you to visit all these excellent websites and read their findings and guidelines. You might also want to engage some help with indexing your publications.
♫ Follow the, follow the, follow the, follow the, follow the innnnndex. ♫♫
The Oxford Learner's dictionary defines a yellow brick road as "a course of action that a person takes believing it will lead to good things". The attributed source is, of course, The Wizard of Oz where Dorothy and her friends must journey through a vast landscape fraught with peril to find the fabled Emerald City nestled, hidden out of sight, find-able only by following the yellow brick road.
So, a robust, highly consistent index in large, highly technical documentation can be thought of as a sort of yellow brick road where User can expect to find all kinds of good things about topics. It's also a handy way to teach User new things.
Here is how an Index serves as a yellow brick road an information product inside of an information product:
- warnings - if it's serious enough, use the index to warn User (backups | do not run during synchronization)
- product-specific terminology - "see" index entries help User learn how your docs refer to something, which may be different from how the industry refers to something (permissions | see privileges).
- similar terminology - "see also" index entries introduce parallel terminology User might also want to search for (high availability | see also fail-over)
- esoteric related topics - index the relationship between components that wouldn't have been intuitive to User (monitoring | performance with histograms (say what?))
- feature support statements - teach User what is supported (FEATURE X | version 11.0.1 new feature), no longer supported (FEATURE Y | version 12.0.1 support removed), intentionally not supported (FEATURE Y | not supported). Feature support history in the index can be very valuable within your organization as well, especially by Support groups.
Once User gets better at using an index, they start thinking in "primary index terms" when searching the index. If you let them, User will even feed back to you on index entries that would have helped them. That's right, User can help lay the yellow bricks. A vast number of SQL Anywhere index entries we've added stemmed from this kind of feedback.
OK, you can stop reading now if you just wanted stats and facts. Beyond this point it's really all just fun.
What if Dorothy used an index instead of the Yellow Brick Road?
In the context of vast documentation sets that have several hundred topics or more (13k topics in the case of ), the table of contents equates to a mere folding map giving general lay of the land, where the cities are and how to get to them. String searching augments this a bit, much like pulling over to ask clarifying questions at gas stations along the way. The information you get is tied to what and how you ask.
But you still don't know what you don't know.
Suppose Dorothy still needed to get back to Kansas but doesn't know how. She hears rumors from the Munchkins about an Oscar or Oz who is a wizard living in a palace using wizardry to solve problems for people. And suppose there is no yellow brick road in this story. Instead, all Dorothy has is a 13k page tome called "Oz Anywhere - In-cloud Guide". It's everything to know about Oz - its history, its people, its geography, etc. and it has an index.
The table of contents has thousands of topics, grouped and nested, but she's running short of time. Plus, she can't remember if she heard the Munchkins say Oscar or Oz. So, instead of scanning the table of contents or text searching for Oscar or Oz, she just hops to the index and types Oscar. She learns pretty quickly that Oz is the way to go, plus she gets the name of the palace confirmed:
Here are the index entries that taught her all this ( the format is <primary-index-entry> | <secondary-index-entry>, where the primary entry is the value she looks for in the index)
Oscar Zoroaster Phadrig Isaac Norman Henkle Emmannuel Ambroise Diggs | see Oz
Oz | also known as Oscar Zoroaster Phadrig Isaac Norman Henkle Emmannuel Ambroise Diggs
Oz | the Emerald Palace
Oz | how to approach
Oz | wizard, great and powerful
wizard | see Oz
wizard | the great and powerful
Now that she has the palace name confirmed, she searches the index and learns a new key piece of info she wouldn't have guessed: green glasses are required for entry.
Emerald Palace | how to get there
Emerald Palace | home of Oz
Emerald Palace | green glasses required for entry
Emerald Palace | how to get in
So of course she wants to know more about the green glasses since she won't be able to get in the palace without them. She learns that not only are they required, but they also prevent blindness in the palace:
green glasses | required for entry in the Emerald Palace
green glasses | use in preventing blindness in the Emerald Palace
green glasses | how to get
Nearby the Munchkins are yammering to her about watching out for bad witches, so she hits the index one last time before heading out, and it's a very good thing she does. By doing so, she learns how to get rid of these bad witches:
witches | good, Glinda the Good Witch of the North
witches | bad, Wicked Witch of the East
witches | bad, Wicked Witch of the West
witches | using water to mellllllllt bad witches
Here are some other index entries that would serve Dorothy well, but only if she'd been a keener to try them:
Kansas | how to return to (ruby slipper method)
ruby slippers | teleportation
ruby slippers | specifying "There's no place like home." while clicking heels
there's no place like home | effect when wearing ruby slippers
At this point, Toto is fast asleep on the grass, and Dorothy hasn't even moved her ruby slippers. She already knows so much about where she needs to go and how to get there. In fact, if she really had been that keener and just read the index entries on the ruby slippers, she could bypass the whole Emerald Palace excursion, skip meeting the lion, tinman, and scarecrow, and just go back to Kansas immediately. But that would skip all the excitement and adventure of wandering about, lost, unknowing and unaware.
Hm, maybe that's why indexes are disappearing from publications: authors don't want to deny User the mysteryof unknowing and the adventure of being lost in the docs.
Credits and References:
SQL Anywhere documentation
BNA Bloomberg
Leverage Technogies'
Publishing Technology Group of the Society of Indexers
Oxford Learner's Dictionary
