Copyright © 2005 by Shaun McCance
Copy away; give credit where due.
In which we disassemble the help system, rethink how we present help to the user, and leave our practices laying in ruins. In which we rise from the ashes of a long-dead but still-breathing behemoth. In which we lay the foundations of tomorrow and dream of the future.
This document was written in 2005 and reflects the very earliest ideas on what has since become Mallard. The document is kept here for historical reference. For current information on Mallard, please see projectmallard.org.
You're an engineer. You have an important project in front of you that requires you to take the derivative of an exponential, but you've forgotten how. So you find a mathematician and ask him. The mathematician tells you to enroll in his semester-long calculus class, and that somewhere in the middle, you'll learn how to take the derivative of an exponential.
Do you enroll in the class? Of course not. You fire up a web browser and open MathWorld or Wikipedia and move on with your life. Maybe you even buy Eric Weisstein a beer. Or maybe that's just me.
Most online help for software is like our mathematician: arrogant and condescending, long-winded where it's not needed, short-winded where it is needed, and ultimately useless. If a user is looking at the help, it means he's stumped by the interface. Instead of helping him, we stump him with the help navigation. Users quickly learn that hitting F1 just isn't worth the effort.
I was recently setting up a mail account in Evolution. The Evolution Account Editor dialog is six tabs thick, and has no Help button. There's all sorts of stuff in there that I don't understand. Put more bluntly, I'm a geek, and I need help with this dialog.
Unfortunately, nobody has made a Wikipedia entry for "Evolution 2.4 Account Editor dialog, Receiving Options tab", and somehow I doubt anybody ever will. So what does "Override server-supplied folder namespace" do? It certainly doesn't appear to do what I thought it would do, so I'll go wade through the help book to find out.
By choosing this option you can rename the folders that the server provides. If you select this option, you need to specify the namespace to use.
Thanks. Reading the interface back to me is not helpful.
Mark Finlay often said that good software doesn't need a manual. And in an ideal world, maybe he's right. The problem is, we're not making that software. Can we clean up our interfaces to make them more understandable? Absolutely, and we should. There's no question that we should have dedicated usability folks involved at every step of our software design.
But the interfaces of today can only be so explanatory. Sometimes, you deal with software that needs to be explained. There's a certain level of complexity and configurability that our software must have to function in the real world. In an ideal world, I should be able to give Evolution my email address and have everything work. But our world doesn't work that way. As long as there are questions, our users will need help.
Our documents today read like stereo instructions. They consist of a long sequence of directions, each relying on the ones before. Each one is as dry and lifeless as it can be, and generally provides the absolute minimum amount of necessary information to declare the documentation finished.
Instead, our help should be topic-oriented. We should focus our help around individual, self-contained topics. As a guideline, topics should be no longer than about two pages. Their language should be casual and digestible, while still being accurate and precise. We should not fear redundancy. If two topics provide some of the same information, we should consider our documents better for it.
How do we do this? Certainly, we could try to write our DocBook to be more topic-oriented. Unfortunately, it's difficult to provide the level of rendering and navigation control we really need to make this actually useful. Good topic-oriented help needs to have a distinct and reliable page output, rather than the whatever-the-stylesheets decide mechanism we use to chunk DocBook. And good topic-oriented help needs to be cross-linked up the wazoo.
So forget linear documents and deep nested sections. Every topic is its own file, ready to be displayed to the user. These are digestible chunks. They're easy to write, easy to maintain, easy to modify, and easy to read. Sure, the topics themselves might have sections, maybe even subsections. But they are not themselves sections of some book. Instead, they are standalone pages.
So say I've written the program Beanstalk. It's a fairly nifty little program, but my users need help with parts of it. Hey, it's not easy to make an intuitive interface for giant beanstalks. My help contains the following files:
beanstalk.xml fe.xml fi.xml fo.xml fum.xml
And here's fe.xml:
Fe ]]>
Boring, right? It just looks like DocBook with a new wrapper element on top. The point is that topic is a top-level element, period. It's not nested in an article or a book. It stands on its own. So how do we get to it?
Beanstalk Help ]]>
The top-level help file has declared that it should link to fe, fi, and fo. When rendered, it will show the introductory block-level content followed by nice links to each of the given pages. If we add a short description to each topic, say with a description element, we can show that on the top-level help page as well.
But what about fum.xml? As it turns out, the fum functionality is provided by a plug-in called Fumstalk. When Fumstalk is installed, it installs a help page that looks like this:
Fum ]]>
Page links are symmetric. Our help viewer notices that fum links to the top-level help file. That means that the top-level help file implicitly links to fum.
The Beanstalk manual is pretty small and trivial. A few of the Gnome help manuals can get by with just a top-level topic list, but what about the rest? For larger works, we have node pages. These are simple pages whose only purpose is to link to other pages. Here's one:
Fe & Fi ]]>
The page is then rendered with the introductory block-level content followed by links to fe and fi, as well as reciprocal link back to the top-level page. Remember, the top-level page will now have a link to fe-fi, because links are symmetric.
The net effect is that you have an interconnected web of pages. Each page presents a single, digestible topic. Users can easily find related information without having to scan through a poorly-indexed book. Reciprocal linking eases the integration of third-party topics, including documentation for plug-ins and distro-specific documentation.
Documentation becomes easier to write and maintain, easier to manage downstream, and easier to read and understand. Everybody wins.
Up to now, we haven't discussed the markup of the actual content. To be clear, when I say block-level content, I mean the basic content model of DocBook. [Cue sighs of disappointment from stage left, sighs of relief from stage right.] But I don't mean the entirety of DocBook. DocBook is too big and too complex. We mere mortals can't hope to keep the entirety of DocBook's semantics in our heads, and that includes me. Something must be done.
Let's look at a breakdown of the sort of markup we encounter:
And now here's a short list of problems:
Structural markup doesn't fit our needs.
DocBook's structural markup is designed around books and articles. It has parts, chapters, appendices, and sections. It has additional structural elements for indexes and glossaries. It has very specialized structural markup for reference pages, essentially man pages created in DocBook. We don't need any of this. Our structural markup is simple. We have pages, and pages can have sections. There's no confusion as to how information is chunked.
Nested block content is evil.
DocBook allows block content inside of paragraphs. This presents difficulties for processing applications and for translators. It also creates content models that list dozens of elements, confusing people who just want to create a document. We don't need this.
Inline markup is too semantic.
DocBook contains over 70 elements that can be used as general inline markup. Often, there is an element to mark up exactly what you need, just as filename. Other times, you have to abuse an existing element, or just use something less specific. The presence of very specific semantic elements leads authors to expect to mark everything with specific elements. When they can't, long threads break out on mailing lists.
We can't encode every concept you might encounter in software systems. Instead, we should provide semantic markup that has sufficiently broad meaning to include all reasonable uses. The replaceable element is useful; the structname element is not.
This is only an overview. A full treatise on trimming down DocBook would burden this document. Such a discussion deserves a document of its own. The points raised in this document provide a direction, but only a team of enthusiastic and dedicated hackers can make change happen.
Copyright © 2005 by Shaun McCance
Copy away; give credit where due.