RE: YOWZA--struck a nerve: Was Help API Documentation?

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

This is the third e-mail I've started.

The gist of the other two e-mails I wrote was that I have no disagreement
with either Walden or Emily regarding about how you gather information, how
you work with the engineers to get details, etc.

Walden's earlier postings hit the nail on the head when he said words to the
effect that all engineering organizations are unique, have their own
culture, have their own needs, and have their requirements.

Walden is in change of documenting a hefty API -- some 14000 pages -- with a
staff of 6. Not to brag but to give credibility to my API efforts: two
employers ago, we were maintaining 11000 pages and supporting 40 engineers
with just 4 people: one working manager, one programmer, and two writers.

For the record, we did have our documentation separate from the code,
although we did check "documentation templates" into the code which matched
our source documenation. The reason for this is that we had object code
customers and source code customers. The documentation was available in
another form to anybody scrolling through the code -- internal or external.
It also provided an additional communication channel between us and the
engineer, because we encouraged engineers to update comment blocks when they
updated the code. We regularly diff'ed the doc templates with our source to
help us writers focus our efforts on the changed material.

=================================

Walden and I are actually on the same page about everything except the
amount of trapsing about the code that I feel is really necessary to do the
job. I will look at the code if it is "easy" and "obvious." I will do my
best to understand things if for nothing more than to be able to ask
intelligent questions. But I'm not going to waste my time figuring out the
tricks of the internals to some code item that users will never see or care
about. If it is important, the engineer will explain it to me. More often
than not, they'll say it's not important and will summarize what is
important for the user to know.

Also, I am not against having API documentation separate from the code. In
fact, I know for a fact that the quality of the documentation will be
superior if maintained external to the code... with the caveat that tools
and processes are in place to assure accuracy of the code prototypes in the
documentation against the ever changing code pool.

Separate documentation gives the writer more freedom in providing useful
information to the user, which may or may not be important to the engineer
if it appeared in the source code. The writers can organize and chunk it
better for the user instead of some of the arbitrary file and directory
usage of the engineer. Hence the documentation is superior.

=================================

This being said, I still took my present employer pretty far down the path
of having REFERENCE information located in the code. (Reference information
and NOT how-to's, overviews, tutorials, etc.)

Walden said in a previous posting that every engineering organization is
unique and has its own requirements. Well, the path that I've been taking us
down has been in line with what our organization wants.

In our case, our API documentation is primarily for internal customers. The
development group has had coding conventions in place for quite some time
dictating to the engineer the minimal amount of code comments to have for
various code items, such as class member functions. When we finally got a
customer who became a source code customer, it became a matter of leveraging
what already should be there. Much of my efforts were spent just reformating
those existing comments and cleaning them up.

One of my co-workers did an excellent job of producing the first version of
our API documentation in FM separate from the code. With other schedule
demands and projects, it remains difficult to keep some of this information
up to date and accurate. It also turns out that most of his REFERENCE
documentation was very concise. "Just the facts, ma'am. The meaning of the
parameters in, what gets returned, what gets modified, and what does it do."
As it should be.

For the most part, it made sense to roll the REFERENCE information into the
source. It did not produce code bloat -- not much more than what the
engineers were already required to write. Then we didn't have to worry as
much about keeping various code prototypes up to date; they came from the
code along with the comments.

For the record, I removed probably 100 pages of a 500 page API Reference
manual after I migrated the REFERENCE information into the code. I'm still
producing a SEPARATE MANUAL for other information that doesn't belong in the
code.

Also for the record, there were three chapters of that API reference manual
that I could not migrate into the code, because it did produce some
seriously ugly code bloat. In this case, I didn't ignore the source code
(one file with every line in the file representing a function; used for
automatic code generation). I copied a code generation program and modified
it for my needs to generate "code for tech pubs" from the source. I run the
tools on this output from the individual input file. This generated output
hyperlinks to HTML-extracted-from-FM. One big happy system with accuracy and
depth and no code bloat.

=================================

Here's where I'm going to deviate from Walden and Emily's position.

I don't know all of the details of the tools that Walden is using. He talked
about using Windiff, which just compares files. He'll know what changed in a
file  which may cover an interface definition that he'll have to document. I
don't know how automated his process is to focus on just the things that
changed that relates to what his department does.

To make a plug for a tool like Doxygen is that it knows the code better than
we do and better than what we can even see. Case in point, engineers do a
lot of tricks. Sometimes, they have elements that get their true definition
after pre-compiling it. So, just looking at the code isn't going to tell you
what it really means unless you're damn good about tracing things. Even
things like the API definitions that you do see are subject to the whims of
the pre-compiler.

Tools like Doxygen perform pre-compiles to resolve these elements. For the
given language that you are documenting, these tools know what code elements
are important to expose to another engineer: classes, functions,
enumerations, defines, structs, etc.

FWIW, I've run Doxygen on code that had no comments (that Doxygen
recognized). The output you get from it (with no plain English) is still
pretty damn impressive and better than I could have done. Another thing it
does that I wouldn't want to do by hand is it traces the code. It documents
who is using what function, where that function resides, etc. It generates
hierarchy diagrams. It automatically hyperlinks to code items that it knows
about when it comes across it other areas. It has optional features to show
source code and also to hyperlink you to specific areas in the source code.
The framework that it builds should not be underestimated and would be
really hard to create by hand in a manual.

>From the perspective of engineers -- the audience of the API -- this should
not be discounted by the typical technical publication's party line "(I
think) I am in tune with the audience; I write what the audience wants; I
know better than the in-house engineers what the user needs." The audience
"are injun-eers" in this case, just like the in-house ones. They might just
know what they want to see with respect to REFERENCE material about code...
otherwise others of their kind wouldn't have developed such software
(freeware) in the first place to extract things from the source code.

I'm saying, don't look this gift-horse in the mouth. It has many hooks with
which you can plug it in to your existing system and enhance significantly
what you are now producing for the API audience. I'm happy that I have an
off-the-shelf tool which has built in support for what most users need for
that language.

This is NOT the entire documentation. This is only the REFERENCE material.

=================================

I've got a Bic lighter in my hand to produce a tiny flame for both Walden
and Emily in their hard-line position about where documentation should
reside.

The code belongs to the engineer. Commented code should be seen as a benefit
to the owning engineer as well as to the entire engineering organization. It
is an asset of the company. We're talking engineering processes here, which
will be unique for every organization.

In my opinion, if tech pubs worked with the engineering organization to
re-format, re-write, and standardize those code comments [not in-line
comments, but the ones that should appear as blocks as the definition or
entry point to some function], there would be significant long-term benefits
to the engineering organization. This holds true even if we're not talking
about an API that is exposed to customers.

Moreover, you'd be able to extract these same comments along with ACCURATE
prototypes for use by documentation. This would produce JUST the REFERENCE
portion of the documentation. [Tech pubs would still have separate
documentation for tutorials and other information that doesn't belong in the
code.] This extracted system would be beneficial even to engineers of your
company, particularly new engineers or engineers re-assigned to projects.

What are the benefits to the user's? [1] Source code customers have
documented code. [2] Source and Object code customers would receive a
comprehensive, accurate (online) reference -- which could be hyperlinked
into HTML or PDF files coming from other documentation sources.

Tech pubs would have to live with the two-edge sword that some of the burden
of writing reference material will be done by engineering (which IMHO is as
it should be). The reference material is generated automatically, accurately
at the push of a button... although language errors from the owning engineer
might creep in. The PROCESS that you implement for your organization for
working with engineers and their source code will determine whether or not
you get to fix their language blunders: an entirely separate issue subject
to your own company's politics. YMMV depending on the process you put in
place.

And to take issue with another position that Walden and Emily have, you
underestimate the writing abilities of your engineers. If they know it will
be exposed, [1] they can willingly let you edit their comments, [2] they can
let management dictate that you edit their comments, [3] it can be left as
the engineer wrote it.

With regards to number [3]: let's look at the big picture. Is it really
going to matter to the API documentation audience -- ANOTHER ENGINEER --
whether the engineer who wrote the comments had a typo, a run-on sentence,
or other language blunders? (Will the audience -- ANOTHER ENGINEER -- even
see the error [maybe] or care [no]?)

Yes, there are cases where the mistake is major; but in my experience, most
of the things I've fixed from code comments were minor things and MADE NO
CHANGES TO THE MEANING. I just prettied it up. Hence, to be all
anal-retentive about owning the documentation (when the reference
documentation is really the code itself belonging to the engineer) is
out-of-line.


Hence, for wanna-be (or have-ta-be) API documentation writers, I repeat that
tools which can extract things from the code can be your friend. I also
concur with the other postings that the extracted documentation DOES NOT
COVER everything. It just makes up one piece of the puzzle. And for what you
get (for free in some cases), you can't beat the leg up it gives you.



Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com


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

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