She wrote:
I don't think we can ever really know (depending, maybe, on our audience) what is a common-knowledge detail to them, and what is not. My personal frustration with software documentation for aps that are new to me is when they say something like: "If you'd like to perform X function, just use the Y-enator while holding down cntr." No screen shot, no tip as to where to find the Y-enator, let alone what its primary function is (and you'd assume it has a primary function that isn't X, since it's a Y-enator, not an X-enator.) I'm particularly annoyed with this type of instruction when it turns out that the Y-enator is in a sub-sub-sub menu of a main menu that otherwise I never use - so know nothing about, and takes me an hour to find.
Anyway - if asked as a reader of docs what one wish I had - I'd say: "whatever you want me to know about, tell me :::where::: it is :::first:::. Almost everything else I can figure out on my own. If given a second wish, I'd say: "if your software does not do something the average person would likely expect it to do (my favorite example is that Cool Edit Pro - at least my edition - is a sound editor with no volume control. You have to control the play-back volume from your computer media task bar, or your speakers) then say so, up front.
After over a decade in Tech Writing and seeing more documentation/online Help files than I can count, I totally agree with Evelyn's assessment of documentation. Navigation cannot be forgotten but it is. Software functionality gets buried too easily and the worst part - even after working with a system on a daily basis for nearly a decade, I can't remember every single place where something exists. We have an option to do XYZ - it's a check box on a ton of screens - and if I need to update the doc to say that XYZ has a new thing associated with it (and need to find all references to XYZ), where do I go? The doc. I have accepted that I can remember a lot of things - like anniversaries and some birthdays - but not all things.
The other element is about stating up front what you cannot do in the software. I have over 4000 CDs, tapes, VHS tapes, DVDs, and records (45s and 33s). I used to try to find a replacement for my Excel spreadsheet that tracks them all. I wanted something that could generate reports on the fly. I wanted something that could give me a quick report of all my Metallica CDs or all my Metallica *and* Megadeth CDs. Searched high and low. Downloaded freeware and shareware. Sent my requirements to tech support at one company and their tech support person wrote back, "Our software doesn't fit your needs." That was beautiful. Honest. Not the answer I wanted, but honestly, if I would have spent the time to import the file into their software (and that may have been the issue that they identified as not being able to support, but assume I could get the Excel file imported and then couldn't do all the other stuff I wanted to do.) I learned before spending more than 1 hour of my time that I was going the wrong way.
You should know your audience well enough to understand what they need to know in order to complete their task.
No comments:
Post a Comment