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.
> Bill McClain wrote:
> <First, a general question for everybody, then stratagems for you:
> Does anyone have a feel for how useful these automatic generators
> have proven for developers?>
>
> I think the tools are more useful for TWs than developers. The real
> value of these tools is (IMO) the ability to parse the code and
> create a structured API reference in a specified output format. That
> can be HTML, MIF, or perhaps other formats.
This is correct but it implies some untruth :-). Typically
developers hate writing (I'm not typical), so this sort of approach
makes it easier for the developers to fulfill their minimum duties
with respect to documenting their code. A lot of the typical
programmer/writer friction can probably be attributed to the
difference in mindsets - a lot of programmers are extremely low-level,
linear thinkers. If you ask them to explain something, they'll go
from A to Z one letter at a time. Putting together a high-level,
overview sort of structure is hard for that mindset. This approach
lets them document at the level they're comfortable with.
Additionally, when the API docs are kept in a separate file it
becomes quite easy (almost inevitable, when combined with fact number
one) that the two get out of sync.
Finally, by using the doc generation approach, you at least have
some minimal baseline, and you know what's there-but-undocumented, so
you have a more accurate picture of where the holes in the docs are.
> I would reccommend that a TW work with the developer to write code
> comments, since docs can be generated automatically from code. It
> somewhat defeats the purpose if you have to edit generated
> documentation afterward.
I would recommend this approach, although you should look at the
various special tools for editing javadoc (or similar) and see if you
have one that will help the techwriter avoid inadvertantly changing
the code itself.
I suggest that the writer doing the work should be able to
understand at least the basics of the language in question, or they'll
have a lot of difficulty figuring out the nuances and the
relationships between comments and code. Not only will lack of
code-reading ability make it hard for the writer to do anything more
than spellcheck (and maybe not even that - traditionally programming
has lots of atrociously stupid abbreviations) it will rob them of the
chance to really do what the reader needs, which is document the
the how and why of the code, not just the what.
I wrote something a year or so ago about code commenting
standards, it's currently living at http://www.darksleep.com/. Most
of what I said there could also apply to API documentation.
Last, but not least, as I've said in the past (about API docs, I
think), what programmers want most is examples, examples, and more
examples. The examples should be complete, correct and realistic, or
at least as close to that as possible. Documentation is notorious for
having bugs in it, so make sure you at least compile and try to run
the examples. Ideally you should have a well-documented example suite
that you compile and run with each release. If you have a
professional services division, they might be your best bet to get
more "realistic" examples, as they'll know best the kinds of things
your customers use them for.
Steven J. Owens
puff -at- guild -dot- net
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-Based Help with Macromedia Dreamweaver 4 ($100 STC Discount)
**WEST COAST LOCATIONS** San Jose (Mar 1-2), San Francisco (Apr 16-17) http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.
Sponsored by ForeFront, Inc., maker of ForeHelp Help authoring tools
for print, WinHelp, HTML Help, JavaHelp, and cross-platform InterHelp
See www.forehelp.com for more information and free evaluation downloads
---
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.
