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 the user interface From:jewahe -at- comcast -dot- net (Jeff Hanvey) To:"Kapoor, Shelly" <SKapoor -at- imf -dot- org>, "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Wed, 10 Jan 2007 18:40:41 +0000
-------------- Original message ----------------------
From: "Kapoor, Shelly" <SKapoor -at- imf -dot- org>
> I have to document a couple of user interfaces. What do you thin is the
> best way to proceed? Could you please point me to some tips/ideas for
> documenting user interfaces.
****Talk to Your Clients****
Learn who your client base is and what they need in the documentation.
****Make a Plan and Prioritize Features****
Features that are vital or that are used each time the interface is accessed should be a priority.
Features that are optional, or that aren't used regularly, should be noted but held until the priority features are documented.
Frequently re-evaluate the priorities to ensure that features are being documented in a timely manner.
****Break the Features into Tasks****
The documentation should address how to complete specific tasks - and each task should be internally coherent; that is, they should only address the items that affect how to complete that feature. If necessary, break those tasks into it's constituent parts. Always remember that a short, focused topic is always preferrable to a longer topic that addresses several different points.
One of the main points is that you should not "follow the interface" to organize the material. In fact, I've found that doing so often introduces redundancy into the topics and procedures; leads to long, unyieldy procedures; causes information to be buried too deep into a heirarchy of headings; or just plain limits your ability to add and change topics as needed.
****Use Screenshots Effectively****
As someone else said, a picture is worth 1000 words, but that doesn't mean that you should suddenly start adding pictures after every step. I reserve a screenshot to illustrate an important event (such as checking an option causing the label of that option to change, or other options to appear on the screen). Usually, a good screenshot at the beginning of the procedure should suffice.
Also, I find it annoying when writers include a screenshot of every single error message that a program displays. I usually add a bulletted list at the end of the procedure (usually at the "saving" or "applying" stage) that addresses the various errors, since that is usually when you see them.
Another possibility is to build a screen reference library. Each screen gets its on topic, with a description of all the fields. This prevents you from having a lot of notes about how many characters a field can contain and other such information. The screen library is especially useful for online documentation - each time the screen is mentioned, you can link to it, and focus more on the features you're trying to explain within the topic itself.
****Use modular text whenever possible****
Rather than having to recreate the wheel for each procedure, shunt repetitious introductory tasks into their own procedures. Especially procedures that address how to access a screen or whatever. Again, in the online world, this makes life much easier.
****Build In a Review System****
>From the start, get as much buy-in from programming, quality assurance, telephone support, implementation, and any other group you can think of. These people have the knowledge, and should be a part of the process. I've found that when I've made the documentation process collaborative, people start respecting it a lot more, and are more willing to tell you when something is wrong - or just to pass on information.
****Only Document Your System****
Our documentation starts with input and ends with the output. How the input information is created is not part of our documentation, nor is what people should actually do with the output file.
Of course, I'm in a banking environment, and the input and output often takes the form of electronic interface files (ATM transactions, paper transactions, etc), and most of the files are disposed of electronically in some way (emailed or FTP'ed to a third party). We do have a couple of procedures on using the Mail Merge feature in Word and importing files into Excel, but that was only after we had a lot of requests, and customer care was having to train people on these features.
****Build a Style Sheet****
Develop styles and templates to enforce a consistent look and feel to your documentation.
That's all my major points. I'm sure I've left out something.
Good luck, and don't be afraid to ask for additional help.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
