Re: Code comments as Documentation

Subject: Re: Code comments as Documentation
From: "Janet Swisher" <swisher -at- enthought -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 1 Oct 2004 10:56:56 -0500

Leigh Price <price_leigh -at- yahoo -dot- com> wrote:
> <sarcasm>Oh well, I guess I'm just a pathetic
> technical writer who would rather focus on creating documentation for
> end-users than cleaning up code comments that are not written for public
> consumption.</sarcasm>
> Many PPs indicate that their department uses code
> comments as the basis for doc. That's different.

Sarcasm aside, nobody suggested you had to clean up code comments "not meant
for public consumption". If your organization uses the code comments to
generate doc, then they are meant for public consumption, and are therefore
part of your concern as a tech writer. If your organization doesn't do that,
then you don't have to worry about it.

As a tech writer, you only have to worry about the code comments that are
used in the doc -- the rest you can leave alone. For any automatic document
generation system (such as Javadoc or Doxygen) to work, the doc comments are
clearly delimited and structured. (In Python, the language actually
distinguishes syntacticly between plain comments and "doc strings".)
Further, unless the organization is shipping source for compilation or
examples, you only need to worry about the doc comments for the public API,
and can ignore the rest.

Maintaining documentation in code requires organizational commitment. If the
organization wants to do it, they need to trust their techwriters to access
the source files, using the same QA procedures that programmers use. Without
that level of trust in techwriters, the effort will fail. The process needs
to be clearly defined and communicated to everyone involved. In other words,
if programmers have a bad attitude towards tech writers, their managers need
to encourage attitude adjustment. If managers have a bad attitude, they
don't have the required commitment.

Janet Swisher
Senior Technical Writer
Enthought, Inc.


ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!

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!

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 for more resources and info.

Previous by Author: Re: OT: Office Chairs (Balance Ball Chair)
Next by Author: Re: I need a user-friendly term
Previous by Thread: bmp to gif to Frame
Next by Thread: Re: tooltips for web-based apps?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads