First time to France, and your goal is to take in the Louvre. You grab a cab at Orly Airport and are relieved to find out your cabbie speaks your language, has been a cabbie for over 20 years, and knows Paris like the back of his hand. You tell him you want to go straight to the Louvre. As he pulls away, you take out a tourist map from your bag, spin it around a few times to get your bearings, and then say something like, "OK, let's see here. So according to this map, we can get there if we take Avenue du Général Leclerc for about 5 kilometres to Place du Carrousel, and then hmmm looks like we then turn right onto Avenue de la Porte d'Orléans, OK? And then..."
Of course, this is rediculous. You don't need a guide to guide a guide.
Documenting a good wizard is similarly rediculous, and as authors we should resist this temptation. Improve them if we must, but don't document them.
A wizard is an information product. Yes, a wizard is a utility, but it's a utility that teaches using screens adorned with information that arrives precisely when (and where!) it's meant to.
Gandalf: "A wizard is never late, Frodo Baggins. Nor is he early. He arrives precisely when
he means to." J R R Tolkien, Fellowship of the Ring
Wizards done right know where User is heading, the best way to get there, and the hazards to avoid on the journey. Wizards give tips on which direction to choose, warnings about hazards, and examples to follow. And they give User reassuring words when the journey is done.
So if we have a good wizard, one with enough tips and examples so that User doesn't need accompanying documentation, why not let it stand alone? Why do we authors feel the need to document it?
- Is it because we have a mindless guideline left over from the 80's telling us to exhaustively document all screens of the UI?
- Is it was because we aren't familiar with wizard's subject matter? It's all gobbledy-gook to us, and we assume it will be to User, too..
- Is it because the wizard was new territory so we treated it differently? For some of you reading this, you can remember when the first step of some wizards was how to open your CD drive, and which direction to place the CD in the tray. We were just sure that former floppy disk users would be completely lost without that step... :smile:
- Is it because the wizard is bad?
Hagrid: "First - and understand this, Harry, 'cause it's very important - not all
wizards are good. Some of them go bad." ~ JK Rowling, Harry Potter
OK, you're reading this thinking, "You don't know our wizards. They are pretty bad; they NEED accompanying doc."
If you think this, you are probably right. I've seen such wizards. I've endured such wizards. But the de facto answer needn't be adding docs and forcing User to split attention across two information products.
Instead, you might consider leaving the shire and going to ask the UI team to incorporate the tips and examples from the docs directly into the wizard screens (ideal!). After all, a user-centered best practice would be to deliver a simplified/unified user experience.
Gandalf: "If you wish to change the weather of the world, you should find yourself
another wizard." J R R Tolkien, The Hobbit
I realize that improving the wizard isn't always an option, though. Whether for obstacles of technology, cost control, or cross-team differences of opinion, you simply can't get the wizard to deliver what you want it to, and it cannot stand alone.
In that case you're out of luck; you need to create doc for it. BUT if you are going to create doc for a wizard, at least consider a minimalistic approach to documentation. Document only what you think the user couldn't figure out themselves.
So instead of reams of pages with content like: "Step 98: In the Table Name field, specify a name for the new table", just give User a one solid topic containing tips and examples for the trouble spots. Cover only those things that would prevent rework, loss of data, or a support call. For example, "When you get to the Configure Security screen, specify protocol options for the database you are creating, do not specify the protocol options of the database you are connected to."
To sum up, leave a wizard alone if it's good. Don't document the wizard.
If it's not a good wizard, drive improvements into the wizard with the goal to eliminate the need for companion doc.
If you can't drive improvements into the wizard and you must resort to creating doc for it, employ a minimalistic approach to documenting the wizard: document only the information User needs and couldn't have figured out themself.
