TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Documenting a "wizard" From:"Stuart Burnfield" <slb -at- westnet -dot- com -dot- au> To:"Techwr-l" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Fri, 09 May 2014 11:32:17 +0800
On Thu, May 8, 2014 at 2:47 PM, Hannah Drake wrote:
>_ My argument is it's redundant, because the wizard explains
exactly_
>_ what it is__ IN the wizard itself (I know because I wrote the text
and_
>_ helped__ design the__ wizard). I also pointed out that if we have
to_
>_ document the wizard, we__ failed at creating a useful wizard._
Hannah, you said exactly what popped into my head when I read the
subject line. There's not much worse than the so-called 'friendly'
wizard that has a field, a Next button and 100,000 grey pixels, and
sends the user off somewhere else to read instructions that should fit
easily in all that unused space on the dialog box.
Documentation should be limited to 'Before you begin' or 'About this
task' material. Robert's example of a checklist is a good one. You
don't want them to have to stop in the middle of the wizard to get
some vital information from a network admin.
Kate suggests you could document tips and tricks and examples, but if
this sort of information would be necessary or useful, a wizard is the
wrong interaction model for that task.
Good luck with your colleague, Hannah. May all your wizards be
Gandalfs and not Sarumans :^)
--- Stuart
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Doc-To-Help 2014 v1 now available. SharePoint 2013 support, NetHelp enhancements, and more. Read all about it.
