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

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

I actually agree with almost everything Emily said here.
My discussion with Glenn is whether tools get you a reference manual.
Whether the documentation for a reference and programmer's manual should
reside in or out of source code.
And who should maintain the documentation/comments.

Most of my API work consists of attempting to understand how to use the API,
not what each function does.

However, when there are 700-1000 functions and tight deadlines, keeping the
reference up to date is a concern.  And that is where tools can be of
assistance, but it doesn't replace communication capabilities.

more comments below...

> As a long-time API documentation writer, I felt that the universe Walden
> and Glenn describe is not one I would ever be willing to enter:
> From their discussion, one might surmise that they both, either using
tools or their
> bare eyes, glean most of their knowledge about how the software they are
> documenting works, from the code.

How functions work... in many cases yes, if specs are not available and
programmer's are not available.

>
> In my experience, both as a programmer and as an API documenter, THERE IS
> VERY LITTLE INFORMATION IN THE CODE.  Lots of useful data points, but
> little information.  Stuff for a reference manual is definitely
> in there --

Source code is exactly how the code works.  Granted you have to trace
through a lot of code to figure it out sometimes..., but what a reference
manual needs is detail and examples.  Source code can provide insight to
both.

> you can get the list of classes, with their associated methods and
> attributes.  But descriptions of what those methods and
> attributes do, what
> the parameters actually mean, why the class hierarchy is the way
> it is.  No
> way.

Neither Glenn nor myself have stated that you can somehow get the meaning of
parameters, etc. from reading code or from using tools.  Instead, the issue
is whether tools help you track changes to API's and whether
specs/comments/documentation about the API's (parameters, classes,
descriptions, etc.) should reside in the source code.  Glenn and I agree
(sorry to speak for you Glenn) that the engineers are the source of that
information, not the code.  However, you can fairly easily figure out what a
parameter (for example) is used for or where it comes from by tracing,
reading, searching code.
>
> Expecting/asking programmers, who are usually an extremely sleep-deprived
> lot, who very often have minimal skill at speaking/writing in
> English, who
> don't have time to step back and think about code from an API-user's
> perspective -- to update comments in code -- well it's just not going to
> happen.  And, frankly, comments in code usually just refer to why the
> programmer implemented a particular loop one way vs. another.

My point exactly.  I read code and ask questions.  Interviewing programmer's
is extremely important.  BUT,
if you can't ask informed questions, these sleep deprived irritated
programmers often will turn on you.

>
> Real developers almost never document stuff that real API users want to
> know, not in code at least.  Maybe in specs.  But then most of my clients
> don't of course have specs.  And, if they do, they don't maintain
> them.  And even if they do maintain them, they don't maintain
> them in sync
> with the code.  And the level of detail in a spec -- well -- it
> depends on
> who wrote it.  Usually marketing did, and they wrote it before
> they really
> actually understood what an API is.
>
> My ability to read code (and, actually, to write code) is vital to my
> establishing credibility as an API documenter with the engineers.
Right.
>
> But, to actually write the documentation, the tool I need most is: the
> ability to talk with and understand the engineers in the language they
> speak (which is often heavily-non-English-accented-technospeak
> (Java, C and
> C++, liberally interspersed with object-oriented-jargon) so that I can
> cajole them to give me the short amount of time I need from them when I
> need it most.

Right again with the following caveat: Often the library/method/function
developers do not know how a function or library will be used by an
application developer.  They are merely writing functions to a requirements
specification. How to use the API is often left to QA, Tech Support,
Training, Documentation, etc. These are equal information sources for
Programmer's Guides, Tutorials, etc.  The Reference docs are very much the
programmer's realm.
>
> It is the engineers who know what features have been added and why an
> end-user developer (my readership) would use them and HOW an end-user
> developer would use them.  It is also the engineers who know why certain
> features are implemented in particular ways and what the consequences of
> these decisions are for end users.  This information is almost
> NEVER in the
> commented code.
I disagree entirely with the first part and agree entirely with the second.
Engineers may never have used the API to write a full application.  I know
in the interactive TV world this is absolutely true.  In the imbedded
systems world it is true more often than not.  OS programmer's have often
never written a driver, but have implemented all the functionality so that a
driver can be written.
Programmer's may know why a feature was added, but not have any specifics on
how to use the feature in a real application.

>
> I do not attribute my nearly-100% (knock wood!) rate in getting engineers
> to actually help me find the information I need for my API
> documentation to
> my sparkling white teeth or nice complexion.  Nor do I attribute this to
> luck or reading code with or without any particular tool.
>
I don't attribute my ability to get information on my good sense of humor
(but it helps).
I also rely on interviewing techniques and I will stoop to bribery, threats,
etc. to get info from recalcitrant programmers (camping out in their cube to
do copy-editing until information is provided often has a quick turn
around).

(had to cut out a lot of emily's post to get it by techwr-l filters.  The
stuff I cut out I agree with)
...
>
> In reading Glenn and Walden's dialog, I got the feeling they were giving
> people a false sense that by using tools or by reading a lot of code, one
> could just turn oneself into an API writer.  What I am getting at is that
> you need quite a bit of experience in dealing with code and
> CODERS to spin
> code into documentation.

NO, but I believe if you can't read code, then you probably shouldn't be an
API writer.
You get experience with experience. Not everyone can be a 20-year programmer
and a tech writer.
I have trained many API writers.  The first thing they have to understand is
code; they don't have to be able to write it fluently.  But they do have to
be able to read it well enough to ask informed questions.
Next they have to get along with engineers and that does mean meeting them
on their own turf.

> I have 20 years of experience as a programmer and I know that there's NO
> WAY that I could document the APIs I write about by just reading code or
> javadocs or anything else  dumped out of source code control.  I do use
> these tools to do my job, and they do often make my job somewhat easier,
> but, fortunately or unfortunately, in my experience, being an API writer
> mostly requires a combination of technical experience (taking a
> programming
> course is not the same as having experience in writing programs) and a
> peculiar kind of people skill (the ability to shoot the breeze in a
> buzzword-compatible way) that other tech writing does not.
>
> --Emily

Again, I don't think that Emily is that far off from my position.  In fact,
Emily does not address the main discussion between Glenn and myself: where
should the documentation reside and how should it be maintained.  Directly,
Emily says she uses tools, but I infer she maintains all documentation
outside of the source code.

I think anyone interested in becoming an API writer should read all of these
points of view and then run for the hills.  Besides taking a certain people
skill and a certain technical experience, API writers must be somewhat
warped and masochistic individuals ;-)

Walden


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

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