Re: Code comments as documentation?

[Chris Gooch <chris -dot- gooch -at- lightworkdesign -dot- com>]

I use perceps to generate API ref docs from C++ code, I've
also heard good things of Doxygen. Of course you can roll
your own system too.

As a general idea, generating (at least some) docs from code
is a good idea, at least for reference style material, and
especially if you are documenting something like an API / SDK
(although there might be other situations where an end-user
might enounter a large bunch of relatively simple things and
need some simple reference docs for them, the increasing
number of third party plug-ins for large apps for example).

Geoff's warning about such an approach leading to code-centric
docs rather than user-centric (or task-centric) is a valid one,
but to my mind having reliable reference style information
should not be a barrier to creating a task/user based layer
above; just the opposite.

Other things to bear in mind;


Technical issues:

*  access to perforce/css/rcs/whatever will obviously be required,
   and you'll need to learn how to use it properly

*  code bloat is a non-issue, comments are not compiled, and
   the comments will take up less room as text than a bunch
   of Word or Frame docs would so actually you are _reducing_
   the space used on the server (what do you mean you don't
   keep your docs in the revision control system?)

*  breaking the code; well don't! You should of course know
   enough about programming not to do this before you embark
   on this approach. No it won't take long to learn. Probably best
   to learn how to compile too so you can check you haven't
   broken the build before checking in. This might mean you
   needing a compiler, which could be an issue (perforce plus
   visual studio will cost more than frame for example)

*  less obviously to non-programmers perhaps, be aware that
   your friendly local build engineer will turn into a dangerous
   psychopath if (for example) you check in .h files which are
   included by every .c file in the system, causing the overnight
   build to go from 4 hours to 48 (not impossible if you support
   more than one platform).



non-technical issues:

*  you will be generating docs from comments _that were
   written with the intention of being used for that purpose_
   of course. It may not be wise to expose some of the
   comments that get written into code to your customers!

*  the tech writer and the developers will need a good
   understanding of who does what and how you work
   together without stepping on each other's toes. My approach
   would be to get the devs to do as much of this comment
   writing as possible, whilst keeping the final say on edits
   to them to the tech writer.

*  don't just learn the local style guide for how code is laid
   out in your shop; work with the senior developer to ensure
   that the style guide includes the things about comments
   that you want included


Finally I thought Bruce's comment about tech writers and
developers working closely was so good it's worth repeating:

+++
The insistence on separating documentation from code seems likely to
perpetuate divisions between writers and programmers. There's nothing
special
about documentation. It's just another part of a product. If anything,
including
documentation in the code tends to make both writers and programmers
remember
that they are working together on a common project - an attitude that tends
to
improve both documentation and code. 
+++

Spot on, Bruce. There's nothing special about documentation,
and likewise there's noithing magical about code. As the PHB
in Dilbert once said, "it's just a bunch of typing".  ;-)


hth,
Chris.

Christopher Gooch, Technical Author
LightWork Design, Sheffield, UK.
www.lightworkdesign.com




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.