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.
Even if the software is not more elementary than you assumed, simply
providing documentation for the specific control may not necessarily be
useful. Our interface consists largely of a series of simple text boxes,
with a dozen or so additional controls, such as checkboxes and drop lists.
All that control-specific documentation could add in that situation is
"This is a text box. Enter some characters." You can't even be specific
about how many characters, because the text boxes (and the fields they
represent) differ in size depending on the data the implementer expects the
user to enter.
More fundamentally, control-specific documentation does nothing to help the
user understand the interface as a whole, much less how to use the
interface. The user needs to know what data to enter in a field, and why,
if they are going to use it effectively. Control-specific documentation is
not going to provide this level of support. If the interface consists of
four different text boxes, each with a different label, just telling the
user that each one is a text box that stores some characters is not going
to contribute much value to the product. Helping the user understand the
interface and how to use it does add value.
That's certainly what I would like to achieve with our documentation.
Unfortunately, it probably means relying on the implementers in the field
creating these interfaces to provide that documentation. The goal is to
find a way to make that process as painless and efficient as possible for
them.
Jim Shaeffer suggested that I "glossed over this phrase from the original
poster": <<complete with forms, dialog boxes, and menu
commands that we would never have foreseen.>>
True enough. I assumed that the original poster meant that the developers
know all existing interface objects, but have no clear idea how they will
be
combined in practice--rather than assuming that the users could create
interface objects nobody had ever seen before. In hindsight, not
necessarily
a good assumption, but if true, the task is very similar to documenting a
programming language's API, and checking the archives for information using
related keywords could provide additional insights.
But as Jim suggests, if the software is more protean than I imagined, this
is a truly intractable documentation problem.
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law."
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Experience RoboHelp X3! This new RoboHelp release combines single sourcing,
print-quality documentation, conditional text and much more, into the most
monumental release of RoboHelp ever! http://www.ehelp.com/techwr-l
Enhance, optimize and automate your FrameMaker-to-PDF workflow with TimeSavers:
Define all PDF features in your source FrameMaker files ONCE, distill MANY.
Bookmark Controller, Link Controller, UnBloat & more : http://www.microtype.com
---
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.
