Re: Code comments as documentation?

Subject: Re: Code comments as documentation?
From: Chris Gooch <chris -dot- gooch -at- lightworkdesign -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 1 Oct 2004 11:21:39 +0100

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
about documentation. It's just another part of a product. If anything,
documentation in the code tends to make both writers and programmers
that they are working together on a common project - an attitude that tends
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". ;-)


Christopher Gooch, Technical Author
LightWork Design, Sheffield, UK.


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: Telecommuting
Next by Author: Editing an Acrobat File
Previous by Thread: TECHWR-L Premium Jobs, Events, and Announcements
Next by Thread: Re: Code comments as documentation?

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

Sponsored Ads