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.
I am documenting a set of APIs for a Silicon Valley firm. Our back-end
server can be accessed through our GUI tools or through these APIs.
Because our customers may use different programming tools, we provide the
APIs in Java, C, and COM forms. Each API consists of dozens of functions
(or in the case of Java, objects and methods).
Every release, new functions are added and old functions are enhanced. A new
feature in the server may require that a new argument be introduced, or a
new reserved value be added to the list of values for another argument. Some
new features will affect more than one existing function, while others will
affect only one, and yet others will create a dozen new functions.
As the engineers do their task, they are obliged to create specifications
for what they are doing. The current release's spec directory contains 32
subdirectories (one for each new feature). Some of them contain only one
spec and some contain as any as 4. Each spec can address changes to all APIs
or some reduced list ("the C customers need this, but the COM customers can
wait until next release").
MY problem is how to organize this set of specs for each such release such
that they can be maintained by the engineers during the release, and used by
the doc person (me) to make the corresponding changes to the manuals.
Currently, they tend to create a new spec for each feature, so some specs
affect 1 existing function, others affect n existing functions, and so on.
They create a spec whose name may be something simple like UserFailureCode
or QuoteClustering, but too often tends to try to tell a whole story:
EngineFilterSupportInCheckParaValuesReturnUpdateAndCheckBatchReturnUpdate
The doc is a typical reference manual, organized alphabetically by function
name. I find it frustrating to keep track of what functions are affected by
what specs, to make certain that all new features are covered. I can't
expect the engineers to keep a running spec for each function and its
changes in this release.
One possible alternative might be to have each spec have a required section
near the top that enumerates the functions that it affects (either makes
changes in or creates).
Do any of you have any architectural suggestions -- things that worked for
you? or perhaps horror stories about things that did not work well?
--Guy K. Haas
Software Exegete in Silicon Valley
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out the new release of RoboDemo, our easy-to-use tutorial software.
Plus, buy RoboHelp Office in August and save $100 with our mail-in rebate.
Get details and download free trial versions at http://www.ehelp.com/techwr-l
---
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.
