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

Subject: YOWZA--struck a nerve: Was Help API Documentation?
From: Berk/Devlin <armadill -at- earthlink -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 27 Apr 2001 12:36:40 -0700

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


Previous by Author: Part-time Tech Writing Moms (or Dads)
Next by Author: RE: .php files
Previous by Thread: Re: non-Adobe prog. for editing others' PDFs?
Next by Thread: RE: YOWZA--struck a nerve: Was Help API Documentation?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads