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.
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.
1-512-536-1057
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.
