Re: Code comments as documentation?

Subject: Re: Code comments as documentation?
From: jsokohl -at- mac -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 4 Oct 2004 11:32:33 -0600

> 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.

Actually, in my case, it's the correct path to take--the documentation is
to define how the software works, not how a user uses it. We sometimes
mistake the word "documentation" to mean "procedural documentation,"
forgetting that there is a place for process doc, design doc, and
referntial doc, all of which describe rather than impel.

Many thanks to those who'd responded on topic. I do have some good
strategies to use with my software engineering lead. I believe the right
approach in my situation is to make the changes in the code comments
sections of the SQL/PL, the JavaScript objects, and the Java Server Pages.
We use PVCS, and I already check out/check in the RoboHelp files (the
previous doc person had the config mgr do this for her, deleting the
contents of the PVCS help direcvtories EVERY TIME a new help build
occurred. Shudder.....).

All the best,



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: Neophyte - impostor looking for advice on contract tech-doc job
Next by Author: Re: Software Requirements Specification Question
Previous by Thread: Re: Code comments as documentation?
Next by Thread: RE: pdf maker

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

Sponsored Ads