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

[Berk/Devlin <armadill -at- earthlink -dot- net>]

On Thu, 26 Apr 2001 09:36:46 -0600 or so "walden miller" 
<wmiller -at- vidiom -dot- com> and Glenn had a heated discussion about the tools they 
choose or don't when writing API documentation.

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.

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

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.

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.

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.

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 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 think I get the information I need because I am usually able to 
understand the concepts very quickly because I do have a LOT of experience 
in implementing these kinds of things.  And the engineers know it because 
usually after one short discussion with an engineer, I am able to document 
their feature well enough so that what I've written is close to what the 
engineer would have wanted to say.  Which means that when I do write it 
down wrong, the engineer is comfortable saying, sometimes not very 
politely, "This is not correct."  But usually, they'll just look at it and 
say, "This is good, but I forgot to tell you ...".  Or, they'll say, "This 
is fine, but this part over here is just a little backwards."

If not tools or code, how do I get the information I need?

First, I attend the regularly-scheduled programmer meetings.  At those 
meetings, programmers explain their decisions to each other.  They also 
discuss the interactions between modules and they offer suggestions to each 
other and discuss how to address bugs.  Usually, at the meetings at which 
new release are defined, I learn what new features are going to be added, 
which engineers are responsible for them, what the schedule is (it's always 
too ambitious at the beginning).  As the weeks pass, I learn which features 
are completely implemented (so I know which features to document first and 
I also know which programmers are caught up on sleep so I can more easily 
speak with them), I learn about how the plan is changing, and I let them 
know what information I need from them and what my time schedule looks 
like.  Just so you know, these meetings drag on for hours and are often 
scheduled for really inconvenient times -- like -- 5 p.m.

Second, I almost always have at least one programmer-contact for every 
important feature of the product.  That engineer nearly always WANTS the 
API users to know exactly how to use this particular feature.  Unlike with 
other software, every one knows that it's not easy to use or 
intuitive.  Which means that that engineer is always willing to:

1.  Eventually, tell me what points he or she thinks should be made;
2.  Eventually, give me an overview of the feature;
3.  Eventually, read what I write and let me know where I've gotten things 
right or wrong.

But timing is everything.  If the programmer is in the process of squashing 
a high-priority bug and I call up demanding some quality time -- yeah, right.

Third, I choose my questions and the venue in which those questions are 
asked.  If I find a misplaced semi-colon (and I do, very, very often), I 
don't ask about it at a group meeting.  I send the programmer an email 
pointing out what I perceive to be the problem.  I find email to one 
specific person is the most effective means of getting answers to 
particular questions.  And, when programmers send emails back, I don't have 
to worry that their Russian accent makes it hard for me to differentiate 
between their "b"s and their "v"s.  (Programs won't compile if the method 
names are misspelled!)

Also, I strive to NOT participate in the technical discussions during team 
meetings.  The role of a tech writer is a "humbler" role than the role of 
developer.  Kind of like the doctor/nurse relationship I suspect.  There 
are times when I truly feel that I know more about a problem than the 
developer who is trying to solve it.  But the political reality is that the 
developer would not want me to help solve the problem in a public meeting 
in front of other engineers.  And, it's also sometimes true that the 
programmers have more knowledge about the details than I do, so the 
suggestions I might make would sound foolish.  I need to make sure everyone 
knows that I understand the technical issues "nearly" as well as they do, 
but I can't come off as either defensive or superior.  Which is why I 
"settle" for "nearly" as much money as they make but can pretty much set my 
own hours, and don't have to work many 80 hour weeks, which I know many of 
them do.  (And, no, anyone who knows me knows I am not a person with low 
self-esteem and no, I do not really consider myself "humbler" than the 
developers.  But I don't see any way to do this job without implicitly 
acknowledging to them that they are the experts in terms of the content and 
even -- often but not always -- in terms of how it is presented.)

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.

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

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~                            Emily Berk                                 ~
On the web at www.armadillosoft.com *** Armadillo Associates, Inc.      ~
~             Project management, developer relations and               ~
extremely-technical technical documentation that developers find useful.~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


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

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