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 meant to respond to this yesterday, but I have a lot to say and I was
just too busy...
I haven't used Doc-o-Matic, but from the description on the website, it
seems to be an automated documentation-extraction tool like Doxygen: You
feed your software team's source-code files into one end, and it
excretes documentation from the other.
If it works like Doxygen, some of the generated documentation -- call
trees, dependencies, symbol tables, function-parameter lists, etc. --
comes from analysis of the code, and the rest comes from comments (which
may include special formatting codes for the documentation generator)
placed in the source-code files by the software developers.
For the software-development team's internal use -- as a development
tool -- I guess Doc-O-Matic could be helpful, although modern text
editors make it largely unnecessary.
However...
If the generated documentation will be distributed beyond the
development team, or if it will be controlled in the same way as other
documentation (i.e., if it's assigned a document number or has to be
checked in/out of a repository), there are a LOT of issues to think
about. Here are ten to start with:
Obvious front- and back-end issues:
-----------------------------------
1. If any of your code is written in a language that your doc-gen tool
doesn't understand, the tool won't be able to parse it.
It's possible to add new language front-ends to Doxygen (if your company
feels like funding that development and your legal department is happy
with Doxygen's open-source license requirements), but it's not easy.
Doc-O-Matic doesn't seem to offer the option at all.
2. If the tools don't output documentation in your preferred file
format, you're out of luck. Doxygen, again, allows new output
capabilities to be added, but your company's unlikely to want to invest
in doing that.
3. Setting up and configuring Doxygen is a pain, and people have the
same sorts of religious battles over Doxygen configurations as they do
over C style guidelines.
Single-sourcing issues:
-----------------------
4. Since source code and documentation coexist in the same file, fixing
even a minor punctuation or spelling error in the docs means a new
version number for the source. If the product has already been released
when this happens, it can be a huge issue, especially if your product IS
the source code:
Someone has to update internal and external web pages, training
materials, knowledgebases, CDs, appnotes, etc., with the new code,
all of the printed and CD-based documentation you've published suddenly
goes out of date,
people call from all over the world asking for the new version of the
software,
customers get the impression that you can't get software right the first
time, or the second, or the third...
5. Since software developers generally don't write polished
documentation, the comments they embed in the source code must be edited
by a technical writer. That tech writer must be trusted (and willing)
to modify software source-code files without screwing anything up.
6. If your shop uses a version-control system like Visual SourceSafe
(which allows a file to be checked out by only one person at a time),
the documentation-editing process can't begin until the code-writing is
done.
Issues with using it even as an internal development tool:
----------------------------------------------------------
7. Every day, I see code with comments that haven't been updated when
the code has. Automatically generating documentation from comments that
are wrong won't make them correct OR useful OR up-to-date.
Unfortunately, the high quality of the generated output's PRESENTATION
-- it's usually really pretty, with nicely-formatted tables and lists --
gives the illusion that its CONTENT is of similar quality.
8. High-quality source code is easy to read.
Your programmer might always keep his comments correct, and he might
even be one of the two or maybe three that I've met whose comments were
written well enough to stand alone as software documentation... But if
he's forced to punctuate his accurate/complete/well-written comments
with your doc-generator's messy formatting codes, his code will never be
easy to read.
9. Relieving a programmer of the busywork "burden" also relieves him of
its benefits.
I used to own a car with an oil-level gauge on the dashboard, but I
still checked the oil manually because opening the hood let me glance
around in the engine bay and maybe see if there was anything going wrong
in there. Looking "under the hood" in order to manually document his
code gives your programmer the same opportunity.
10. Similarly, one of the best ways to debug code is to go through it
step-by step, explaining it to someone else, even if that other person
never speaks.
Invariably, the explanation that begins, "This code should be working!
Look, all it does is..." ends with something like, "...and it's ok that
I'm casting it to a char here, because it'll never be larger than...
Oh."
Using automated tools to do all the busywork means that the programmer
rarely goes through his code step-by-step even to explain it to himself.
Finally:
--------
The automated documentation-generation tools seem to focus on things
like automatic spellcheck, thoroughness of the code analysis, and the
ability to generate visually-pleasing output in lots of formats. This
misses the point, which is that good documentation is about WAY more
than that.
Correctness and clear presentation of the information is important, of
course, but so is writing from the reader's point of view instead of the
author's. A "User's Manual" needs to explain how to USE your software,
but your developers' comments are likely to explain only how they BUILT
it. Not the same thing at all.
I wouldn't hire a poet to write software for me, and I don't expect most
software developers to write good documentation. The availability of
automatic doc-extraction tools doesn't change that.
Just my opinion, of course.
-Andrew
P.S. Actually, I MIGHT hire a poet to write software. But I wouldn't
pay him much.
=== Andrew Warren - awarren -at- synaptics -dot- com
=== Synaptics, Inc - Santa Clara, CA
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
