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.
Matt Floyd is <<... preparing to document a new subset of our software
application that uses dynamic GUI - a means that allows our users to build
their own interface screens - placing certain defined objects on windows and
dialog boxes - according to their specific needs and how they prefer to
collect information. Since there will be no one standardized method of
setting up this application, I may create an object reference section that
displays each application object (for instance, the Customer Name drop down
list, the Address dialog box, etc.). This reference section would describe
the use of the object. I will also include an Instructions section. Some
other sections documented may be an Recommended Setup and Screen Building
Tips.>>
Sounds like a strong basic plan. One other thing you should do, perhaps as
part of the "screenbuilding tips", is to propose common, effective
strategies for building a screen; these would focus on what the programmers
consider effective paths or what you consider good "sample" paths to
illustrate the point without preventing users from exploring and finding
their own paths. Although users could theoretically build screens in any
order, with any random combination of elements, it's far more likely that
certain common paths and common tasks will be used. Identifying these
requires some understanding of your audience and their goals, and perhaps
even working with actual users to see how they typically create screen
designs.
Furthermore, you can almost certainly group elements (e.g., unconstrained
text fields vs. constrained or validity-checked fields vs. pick lists of
various sorts) and provide strategies for each of these groups. Similarly,
you might be able to define a common approach that works for all screens
(e.g., if users must pick a name object, a memo object, and a pick list to
create a valid screen, you can document each of these steps). Finally, you
should make an effort to identify dependencies (e.g., "you can't insert a
postal code field until you've inserted a country field because the country
field determines what postal code format you can use").
<<In the future I would also like our customers to dynamically generate
documentation based on the objects they have placed on their interface
screens, using a online database publishing software with a FrameMaker to
PDF layout component (such as Miramo).>>
If I'm understanding you correctly, you can't simply do this with
conditional compilation because the user could add a new object after the
help file is already created. Plus, you want help available only for the
interface objects they add to a screen. The techy details of that specific
combination are beyond me, but it seems likely that you could fake this
reasonably well in WinHelp or its equivalent if the interface compiler
you're documenting permits context-sensitive help. For example, let's say
the "OK" button object includes its own help topic, with the context ID 007;
if the help topic for each object isn't linked directly to any other topics,
then the only way users can access it directly would be when they include an
OK button in their interface; as soon as they compile that interface, the
help becomes available. Of course, they could still find it indirectly using
the search and index functions, but that's not much of a problem. (In fact,
I'm not sure why you wouldn't provide all the help, no matter what
components the users use. Having it present doesn't hurt, and may even
encourage them to obtain more components.) Each independent help topic could
include a link to a master lookup table of all possible components, which
would then explain how to obtain components the users haven't yet installed.
The effect of this approach is that you provide direct, context-sensitive
help for every object they add, and even though the other topics are
present, they're not directly linked until someone installs their
corresponding object.
--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"The most likely way for the world to be destroyed, most experts agree, is
by accident. That's where we come in; we're computer professionals. We cause
accidents."-- Nathaniel Borenstein
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe. http://ieeepcs.org/2001/
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.
