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.
Joe Sokohl wondered: <<I'm working on a software design description.
Developers are responsible for describing & documenting the software
modules that make up the program. They've decided to use code comments
(both header & inline) to make up the info that describes the modules.
They extract the comments with a script to produce this doc.>>
Sounds great, but it's a completely misguided approach to producing
documentation. The result of this is code-centered documentation rather
than user-centered documentation: it defines how the software works,
but not how people will use it. Think of the difference between a
blueprint and a house and you'll get the idea.
That's not to say this approach won't produce a good source document
that tells you how the code works--it can, if the developers can be
forced to adequately document the code--which can be very useful indeed
when you're documenting how something works.
<<This dynamic approach means the doc can be as up to date as the code
is (assuming, of course, they edit their own comments whenever they
make significant changes).>>
If this is the case, someone needs to take responsibility for
confirming that the comments are comprehensible. The goal of commenting
is to avoid the Adobe/Microsoft phenomenon: after 10 or 20 years of
developing undocumented or inadequately documented spaghetti code, it
becomes cheaper to throw out the application and start over from
scratch. This is not a good thing.
This is what happened to PageMaker, and I'm told it's why Frame
development was abandoned on the Mac. And as for Word? Blech. They
haven't fixed the autonumbering bug and several key flaws in revision
tracking (losing the reviewer's ID, for instance) after 10 years
because nobody knows how.
<<My conern is in what to do with the doc I receive. Do I edit it to
make the often obtuse and sometime grammatically incorrect
developer-originating comments comprehensible, or do I let sleeping
code comments lie?>>
If the goal of the comments is to communicate how the code works to the
programmer who, 1000 years from now, is tasked with solving the Y3K
problem, then you certainly need to dedicate someone to the task of
creating comprehensive, comprehensible comments. If not, at some point
the developers will have to throw out entire modules and rewrite them
from scratch. (That's a strong argument you can make, but the way.
Development managers hate to consider this.)
If the goal is to use the comments for documentation, you need a
technical writer to turn "what this does" information into "how I use
it" information. There's no reason you couldn't embed this
documentation in the code, other than code bloat and the fact that it's
a hideously inefficient way to create docs.
This is a complicated situation, since you need to have access to the
actual code so you can maintain these comments. Developers often hate
to let us touch the code or even see it, so that's a delicate political
negotiation you have on your hands.
<<If I edit them, then they immediately differ from what's in the
code.>>
Which is why you need to edit them directly in the code. Depending on
the software development kit, you may be able to come up with a
compromise. In Delphi, for example, labels are stored in an external
"language" file, and are inserted into the program code only during
compilation. As a result, when I worked for my previous employer, I was
able to edit the interface directly in the language files, without ever
touching the sacred code. The developers loved this approach. Could
something similar work for your code documentation?
<<If I ask 'em to add the edited text back into their code, they do
double work (and they're already frightfully resentful of having to do
documentation of their code in the first place--this dev environment's
rampant with the "just read the damn code" mentality).>>
Think of this as your opportunity to develop a way to take over a task
they hate doing (documenting the code), thereby ensuring (i) that the
job gets done right and (ii) that they end up deeply grateful that Mom
and Dad Sokohl raised a technical writer. <g>
--Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl
WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
