Re: Documenting the User Interface

Subject: Re: Documenting the User Interface
From: Janice Gelb <janice -dot- gelb -at- sun -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Thu, 11 Jan 2007 07:44:13 +1100

Brasel, Russell wrote:

My rubric for user documentation is:

1. Make sure you're very familiar with the UI/App. Make a list of
its functions, etc.
2. Screenshots. Good screenshots. The old adage "A picture is
worth a thousand words" rings true. I use Paint Shop to take the
screenshot and Visio to overlay captions, etc. You can use XP's print
screen, but the resolution is not good.

I would say on this one that It Depends. I've just
recommending removing a bunch of screenshots from
an administrator's guide because the installation
UI mainly consists of screens with self-evident
fields that need to be populated with information
like the user's name and password, port, etc. Where
the interface is straightforward and labeled well,
screenshots can often be unnecessary, taking up
space and making the reader flip more pages without
adding much benefit.

My own list would include a recommendation that
you document the UI in the context of the tasks
that the reader performs rather than for its own
sake. For busy or confusing screens you might want
an orienting screenshot but providing a description
of all menus and screens is usually unnecessary.
Readers are mainly concerned with using the UI to
accomplish the purposes for which the product was
purchased. They rarely want to see screens and menus
for their own sake.

Good luck!

-- Janice

***********************************************************
Janice Gelb | The only connection Sun has with
janice -dot- gelb -at- sun -dot- com | this message is the return address

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


Follow-Ups:

References:
RE: Documenting the User Interface: From: Brasel, Russell

Previous by Author: Monday Funny
Next by Author: Re: Documenting the user interface
Previous by Thread: RE: Documenting the User Interface
Next by Thread: RE: Documenting the User Interface


What this post helpful? Share it with friends and colleagues:


Sponsored Ads