Omit needless instructions

Jenny, at The Creative Tech Writer, muses about the scarcity of documented "best practices" for onscreen help design. I think there are a few factors at play here. First off, those who haven't thought much about Help assume that applying website design practices is "good enough." I think that's misguided, using Help and browsing the Web are only superficially similar, but given that both Help and a website are often authored in HTML the confusion is understandable.

Secondly, most Help authors use tools that are optimized for pouring content into the design and framework provided by Microsoft's WinHelp and its variants. In fact, a selling point of the authoring tools is that you don't have to think very hard about design -- just write (and write, and write) then push a few buttons and you have a help system. It's almost as easy as using a Powerpoint template, and we all know the kind of quality that leads to.

But clearly identifying some best practices will elevate the craft. To that end, I offer my favorite. Write for onscreen use. That is, when a user is reading onscreen Help you know that they're in front of a computer, that they have your software, and they're likely following along with the procedures. None of this is true with a printed book, but it is for Help, so acknowledge these environmental realities and reduce the narrative, descriptiveness, and repetition in your instructions. For example, if the application enforces some action, such as clicking to confirm a selection, omit "15. A dialog box appears. Click OK to confirm your selection" from the Help.

Posted: June 25, 2003 link to this item, Tweet this item, respond to this item