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