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

["walden miller" <wmiller -at- vidiom -dot- com>]

Introductory statement before the salvo:
While Glenn and I seem to have a major disagreement, I do not believe we are
actually
so far apart.  Processes are company dependent and staff dependent.  I do
not subscribe
to any theory that allows for a process is one company to be uniformly
applied to all
companies just because it works in one situation.  Processes are driven by
the individuals
that are within them.  The individuals make them work or fail. I find that
writers are
creatures of process and, given the chance, can crate processes that work
for them and
with others.  Some writers, however, are creatures of comfort and always
want the same
process no matter where they go.  I do not believe that most API writers fit
this
second category because of the very chaotic nature of engineering
development and product
deadline (this characterization fits much of the tech writers' situations).

I welcome any debate and informed discussion of process and the API writer's
lot.
so please read with that in mind. This is long, as were the previous
portions of this thread.

*****
Legend for previous comments:
> = Glenn
>> = Walden

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

Actually, My staff of 6 (including myself) are supporting 14000 pages of API
documentation
(API Reference, Programmer's Guides, and tutorials). I find that the
windiff/source safe types of tools give me all of the source changes in a
quick overview.  I can change all of the prototypes/return values/parameter
changes, etc. in a single day.  The descriptions of the functions and
changes are the hardship.
The interactive television industry is very immature.  The API set grows
every release but the old code usually doesn't change between releases.
During development, the API is very volatile.

> 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.
It is not a nightmare, it is a tools issue, but not a documentation tools
issue.
Its a code tools issue.  Windiff (which I use) provides an excellent graphic
mapping of old code vs new code.
Other tools exist for tracking changes as well.

It seems the real issue (as pointed out eloquently by Glenn) is where the
explanation of the code is maintained.  I prefer it to be maintained in
Framemaker files not in source code. I cannot imagine 3500 pages of
documentation (my current SDK set) maintained within the source code (spread
out over a few hundred files). Keeping up the documentation explanations and
tutorials is hard because it assumes a familiarity with the code.  I do not
have to be an engineer, but I better be able to read code.  IMHO, all API
writers must be able to read code and preferably able to write code as well.

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

Here I must disagree.  API tech writers are in a different class of tech
writers BECAUSE they must know code well enough to read and document it.
This does not mean that they have to be able to write it.

If all you understand is the class method interface, then you really don't
know what the method does.  If you don't know what the method does, then how
can you determine whether the comment changes in the code (by the engineer)
reflect the actual changes in the code. I trust engineers with code.  I have
less trust in their documentation.  Not because they don't have good
intentions, but because they are very much under the gun to deliver product,
just as I am.  I am paid more than a GUI-oriented tech writer because of my
code abilities.  I am paid less than some engineers because I can't write
code as well as they can.


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

You can win most bets about specs, but probably not this one.  The specs are
usually kept up, but the detail level is not sufficient for full
documentation.  The prototype changes in the development process are easily
handled in a spec or source code, but they are just as easily handled by
myself.  I live in the code and the docs hand in hand.  I right on a SUN and
have my PC up and running Visual studio to examine code. The issues I have
with specification updates are the details of how the code works (what the
methods really do).  The complexities that are described in the method
descriptions come from my interviewing engineers and from my reading the
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.
I only check the prototypes that changed.
I know exactly which ones changed because the source control tools told me
they changed.
This is not a problem, but merely a update to existing documentation, which
you would have to do regardless.

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

I do not depend on the programmer to tell me when they change the code.  I
check the code.
I compare the code and the code dates.  There are logical times to do this
during the development cycle. Most likely right after an engineering build,
for example.  During the last product I was working on, there were 56
engineering builds. I didn't start documenting until about build 41, because
the code was tooo unstable.
By being very involved in the engineering process I get to see the direction
code takes and get involved in the design and development process.

Of course there is an incentive.  They have to review the documentation at
some point.  If they talk to the writer on a regular basis about the code,
then the documentation is in better shape by the time review occurs.  The
incentive to help docs along during development instead of waiting til the
end of development and spending lots of time reading and rewriting and
editing and ...

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

I do not see this as an incentive.  I see this as a humbling experience for
foreign programmers with poor english skills.  English should not be a
reflection of their programming skills.
>
> 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.

I am not talking about reverse engineering, I am talking about understanding
code.  Reverse engineering would be if you didn't have the source code
available and you had to recreate the code from the GUI or recreate all the
hidden classes and source from just the prototypes.  This is not an option
in any API writers scenario.

I do not police the engineers comments, I ask engineers what there code
does.  To ask intelligent questions, I must know about the code.

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

All of the engineers on these projects have copies of the documentation,
read the documentation, use it as the starting specification for the next
version of the product, and understand that changes to the code necessitate
changes to the documentation.

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

Here I can find no problem with your argument.  But why can't I just reuse
the API docs in Frame again.  Not a major problem.  We don't really do lite
versions of anything, but I have seen many products that do.

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

The key here is "working with a tech writer."  What I advocate is working
with an engineer.  I propose that API tech writers should be involved deeply
in the engineering process from the very beginning.  The docs should reflect
the understanding of the code and product.  I never let an engineer off the
hook.  They wrote the code and they should stand by it to explain it.  Our
different styles are the amount of interaction between the writer and the
code and the writer and the engineer and the placement of the documentation
(inside the code vs inside a FrameMaker file).

...

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

No, uncommented code and foreign programmers mean you have to adjust your
processes for the situation.  Having rigid processes which do not allow for
idiosyncrasies of individuals usually fail or weed out individuals.

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

I would not go so far as to group engineers into a single melting pot and
assume they all fit a mold in which a writer knows what is best for them.
We are entering an age where India and South Asia may provide a large slice
of our engineers.  Writers and companies (as well as the engineers)
must adapt to cultural and procedural differences.
>
> 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.

Exactly, although your previous comments tend toward shape up or ship out.

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

I have actually discussed this with many engineers who maintain "reusable
code"
with extremely large API's.  They believe that the JavaDoc type tools are
best
used with small to medium size APIs.  Large API's where the documentation
runs
into the 3000-6000 page range (all of Vidiom API projects, currently) are
best
suited to being handled with documentation outside of the source code.

The tutorial is always the last piece to be finished.  The programmer's
guide is
usually next and the Reference guide is first to be done.  The process
however is
iterative and requires the same level of competence required of a
programmer:
When a programmer changes source, her changes can affect other source.  The
programmer
must follow all threads to ensure the small changes do not break the whole.
The writer
must do likewise.  If the reference manual changes, then all appropriate
references
must change throughout the manual set.  That's what I get paid for.
FrameMaker and
other documentation tools allow me to update my documentation, search for
information
and do my job with a minimal of fuss.

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