RE: Help API Documentation?

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

Walden and Lydia are correct in pointing out that auto-documentation tools
are not the end-all-cure-all. If the API is small, you might indeed be
better off doing it by hand.

My posting was based on experience with API documentation that was of some
size. Just about every release, some change was implemented that affected a
whole bunch of code items in their arguments: one added, one removed, one
changed... Sometimes, these changes happened VERY late in the release --
even after a supposed "code freeze".

Without tools, it would have been a nightmare trying to find each and every
one, and it would have been at the expense of "how to" information. You will
**never** get all of this information from even the **best, most diligent**
engineers. It is too easy for it to slip through the cracks.

Let's face it, if the prototype is wrong in the documentation, all of the
documentation for that code item is called into question. All the user has
to do is attempt to use it or simply look in the header file to discover
that the documentation is wrong. The prototypes have to be accurate if it's
to have any credibility at all.

More below...

> -----Original Message-----
> From: bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com
> [mailto:bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com]On Behalf Of walden
> miller
> Sent: Monday, April 23, 2001 2:29 PM
> To: TECHWR-L
> Subject: RE: Help API Documentation?
>
>
> I do not use auto-documentation tools however.  I prefer to either
> understand the code itself or require specifications that are outside the
> code.

Now you are asking for a lot. IMHO, the technical writer probably doesn't
need to know anything below the API level that they are documenting. To
expect them to dive into the code below, say, the arguments to a class's
methods and to understand the internals of those methods (how many times
does it loop? etc.) is expecting too much. If you expect that, then you can
pay me an engineer's salary.

That is the engineers job. The tech writer's job is to extract from the
engineer any nuances about the code that isn't evident at those boundaries
and to learn how to use those pieces as is.

We can require specifications until we're blue in the face. What the code
actually ends up doing and how, that is an entirely different story. If as
you say, you work on the bleeding edge when the code isn't even commented,
then I'll bet dollars-to-donuts that the specification -- if any -- was
out-of-date before the first Alpha release.

> I have used doc tools and I like them for generating the basic
> structure, but don't like them for generating the body of the explanations
> for API functions.

Documentation tools don't generate the body of explanations. Somebody still
has to write them. What the documentation tools do is give you a choice on
where that explanation can reside.

> You can generate new prototype documents easily, but I must ask
> how well one can generate example code, prolific explanations (when
necessary), etc. in
> addition to the prototype information. Essentially, all of this must be
> non-generated or at least heavily edited before ready for prime time.

Exactly. Prolific explanations must still be written by someone. Example
code must still be programmed by someone. It may even require some heavy
editing before being ready for prime time.

This gets into a religious discussion on where the explanations should
reside.

I've done it both ways: separate from the code in another document and
embedded in the code. They both have their advantages and disadvantages.

I obviously advocate putting it into the source code. Why? Because then if
need be, the information has half a chance of being updated by the engineer
whenever they change their code. (Most of the time, changes to underlying
source code does not require a change to the documentation about what the
code item does.)

Sure, the engineer might introduce some major language blunders, but the
correct process can easily solve that issue. If you've implemented tools,
the tools for source control can be enhanced to tell the writers when
changes happened to the comment blocks or to any comment in general. Then
they'll know **WHERE** to look to clean things up. (The disadvantage is that
the engineers have to trust you in making changes to their source code.)

If the documentation is separate from the code, more power to you. No
question that the quality and consistency of the documentation will be
better. BUT I WOULDN'T ADVOCATE THIS unless the tools that generate
prototypes can also somehow automatically compare prototypes from the code
to prototypes from the documentation. It is a thankless job to compare
prototypes for code items manually... again and again and again... and then
all over again each release.


> > The beauty of tools that extract things from the code is that they are
> > written by software developers for software developers. This
> > means that the tools have already made most of the important decisions
about
> > what should be documented. And they do it automatically.
>
> This boils down to trusting the engineers to keep their source
> code comments up to date.  Often this is not done.

No argument there. Happens all the time.

If the engineer doesn't keep their own comments up to date, what makes you
think that they'll remember to tell you when they've changed their code?
They won't. And they haven't had any incentive to, either.

However, if you start exposing code comments that get extracted with the
prototype, that behavior changes. Before, what was hidden, is now available
for all to see. It becomes a direct reflection on their abilities. They see
it when you ask them to review your online version of their code. Their
peers and managers see it. The customers see it.

They gain the incentive to either clean up those exposed comments
themselves, or to allow the tech writer to tweak them.

The end result is something better not only for the paying customer, but for
the engineer and their co-workers for the next time they have to revisit
that code and figure out what it does.

> The comments stay within the realm of accurate, but the only way to know
if the
> comment is accurate is to understand the code to begin with.

Understanding code is helpful. But it is not the tech writer's job to
reverse-engineer what the engineer has done. And if you expect the tech
writer to police comments to code, then (a) you'll need to pay them as much
as a senior engineer and (b) you've let the engineer slack off.

Everywhere I have worked, the engineers responsibilities have been clearly
defined. Coding standards specify not only the amount of spaces to indent
loops, but also the level, detail, and accuracy of the code comments.

> By the time you have corrected all the
> comments, both grammatically and technically, you have essentially written
> that page in the manual.

True, but if you do it in the code, it's there for the engineer to benefit
from it as well. Your efforts put the comments in sync with the code. A
later change to the code by the engineer might necessitate a change to the
comments which they just might see. They will never see it and never know,
if it is separate in the pages of the manual that they don't need to read.

MOST IMPORTANT OF ALL, if that source file gets re-used in any shape or
form, in whole or in part, in one or more products, it is already documented
when a tool is run against the new set of code. Sales influences Development
into making "lite", "medium", and "full-blown" versions of the product.
Development is smart about using tools to include what's necessary; they
develop one and use many times. If we're talking an API, documentation can
be just as smart in using tools to keep up with the product line. Works best
when the source reference documentation is kept for the most part in the
source code.


> By using windif or diff or whatever source change tool, you can
> track actual changes to the code and make the necessary documentation
changes.

This same technique works for tracking changes to code comments for later
potential editing by a tech writer.

> This does not rely on engineers to update specs or comments.

It should. The engineer should not be let off of the hook for fulfilling all
of their responsibilities. Documentation (or working with a tech writer) for
their code is one of them.


> > As it should be. Software developers know that they are expected
> > to document what they do. Even if their code is never exposed to the
outside
> > world, they are expected to comment it. There are few -- if any --
> > reputable software development companies who can afford to have
uncommented code
> > written.

> I disagree.  Software developers should be able to write specs, but not
> expected to write polished documentation.

I agree. In addition to writing specs, they should be able to write code
comments. In fact, this is more important for the usability and
maintainability of the code for the entire engineering organization.

Nobody ever said that it had to be polished documentation. If they can't
write polished documentation, then they need to cooperate with those who
can.

> Also, I work with many many foreign engineers.  English is their second or
third or
> fourth language and it takes them incredibly long hours to write small
sets of
> comments/specs. Whatever they write must be heavily edited.

So? That's what the tech writer is for.


> I work in the bleeding edge industry of
> interactive television middleware.  Commented code is the
> exception because of the huge number of foreign programmers.

Well, well, well. That uncommented code means that the blood will never
stop.

If code re-usability and maintainability are made priorities in your
engineering organization, then such shoddy engineering practices by both
local and foreign programmers will be forced to stop. They just have to be
made aware that it is one of the measurement criteria for considering the
code complete PARTICULARLY if the delivered code is an API. It could be made
one of the criteria against which they are measured for promotion and
advancement. Engineers are goal oriented people who work best when the
targets are fixed and known; this is just another requirement.

It doesn't have to be a death sentence, though. It is easily solved with
cooperation with those in technical writer who do have the skills. I have
worked with many non-native English speakers both here and in Europe.

> Writing the API function information takes very little time.  Writing the
> Programmer's Guide and Tutorial are the real schedule breakers.  API
> information can be kept up-to-date easily without tools.

Sure, it *can* be maintained without tools. The thought of such an endeavor
makes my eyes spin and gives me headaches. And to do it without tools is at
the expense of the Programmer's Guide and Tutorial. An out-of-date reference
item noticed while writing a tutorial immediately side-tracks you into
getting the reference material updated before going back to finishing the
tutorial. A tutorial based on inaccurate reference material helps no one.


> BUT... If you have the right engineering staff and the right documentation
staff
> and ...., then tools are way cool.
>
> Walden Miller
> Vice President, Engineering Services
> Vidiom Systems


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

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems 
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East, 
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline 
April 27. http://www.pdfconference.com. 

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.