RE: YOWZA--struck a nerve: Was Help API Documentation?
... My discussion with Glenn is whether tools get you a reference manual.Emily's answer: Nope, never, not even a reference manual. And certainly not a programmer's guide, glossary, tutorial, etc., etc. Unless the tool we are talking about is interacting with the engineers.
Whether the documentation for a reference and programmer's manual shouldEmily's answer: Far, far, far out of source code.
reside in or out of source code.
And who should maintain the documentation/comments.Emily's answer: ME, of course. But if not ME, then the tech pubs dept. For two years, I watched one of my extremely intelligent and creative bosses play dumb blonde with the engineering dept. "No, I simply cannot figure out how to check the documentation into ClearCase." I think the woman had a degree in nuclear physics from Harvard or something. And, she could, obviously, figure it out because she did manage to check in one single version at the point of the final build on time and without fail. But, somehow or other, she'd NEVER manage to check it in any more often than absolutely necessary.
... Most of my API work consists of attempting to understand how to use the API,Right, because the header files and the javadocs do tell you that much -- what each function does. So, in that respect, the code does become the skeleton for lot of the documentation for the reference manual mostly. And, in fact, for certain developers who never RTFM, the header files and/or javadocs is all the API documentation they ever need. Wouldn't be a whole heck of a lot of work for us API writers if this were true for most developers. Luckily (for us anyway), the vast majority of API users require hefty documentation other than source code.
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.
I am in total agreement here. You start with the code (header files or javadocs). That gives you the basics. But if you stop there, you do not have a reference manual. You need to fill in the information that is not readily apparent in the code to get a manual, even a reference. And there is no tool that can fill it in for you, although there are tools that can extract the skeletons from the code.
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.
I agree that reading source code can give you some insights. But, Walden, here is where you and I fundamentally disagree:
First, deciphering code is a really time-consuming way for the API writer to learn how stuff works. Reading code to write and API is like examining a tree with a microscope so you can write a report on photosynthesis when you know there's a botanist convention having a picnic under that very tree.
Rather than read code and possibly get it wrong, why not just -- ask for the right answer.
...
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.
And, second and most importantly -- No, not always. And you wouldn't want to guess wrong. So, if I did try to guess what the purpose of a parameter was (or its constraints) by reading the code, I would flag my explanation and run it by the engineer. This is not insecurity on my part. I just know that very often parameters are there but not used, or they are called something like ptrToVariableUsedToCalculateTheValueOfLifeTheUniverseAndEverything but, actually, the parameter is actually used as a pointer to a constant -- 42 -- perhaps. C programmers in particular can be very very tricky. And then there are the Java folks. They can't instantiate an object because they haven't yet validated all its attributes. So they use some stupid work-around that I don't have to document. And yet the stupid work-arounds consume like 2/3 of the Java source code.
In other words, sometimes even though I've interpreted the code correctly, I'm still wrong about how I think it works. Or, what's important in it. Luckily, there are people I work with whose job it is to KNOW exactly how the code does really work. And all I have to do is ask them in the right way.
... 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.
Ahh. Here we disagree again, Walden, and I think it's because we work in different environments. Nearly all of the engineers I have worked with, for many years now, are part of the team that is designing the API while they are developing it. (Spec? What spec? Or, if there is one, they wrote the spec too, but now that it is in development, the spec is changing. Hasn't been updated, but is changing.) There are always some more junior team members, who write to the specs. But I've always been lucky enough to be able to interrogate the guys who do know exactly how the stuff will be used.
I have found that certain QA people, especially the old-timers (however that might be defined where I happen to be working) are also invaluable sources of information. On the other hand, many of the QA people I meet are basically programmers-in-training, just getting familiar with the API. Because they are novice users, it's valuable for me to talk with them about how the existing documentation meets their needs or doesn't, but they often know too little about the product to provide answers to my questions about it.
Earlier, I had said:
> 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.
And Walden had replied:
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.
Again, I think this has a lot to do with our different work environments. It depends on how far up the food chain the tech writer's contacts go. For whatever reason, for many years now, the engineers I work with know exactly how their pieces of the API will be used in a full-blown application. And, they also seem to know a fair amount about the specifics of the implementation as well. Walden, I'm thinking this may have to do with the maturity of the products I document vs. the maturity of the ones you document. Very often, but not always, the products I write about are relatively young. So, a big engineering team for me is about say, 60 to 150 engineers, plus QA and support. The smaller the team, of course, the more centralized the knowledge about how stuff works.
Anyway, for you innocent by-standers who might be considering a career in API documentation, this may be one significant difference in API projects you might run across. I LOVE working with the people who originated the API, they are true believers in the product. Sounds like Walden almost never has to deal with people whose egos are that big.
... I don't attribute my ability to get information on my good sense of humorI find that bringing really good chocolate chip cookies (not the kind that routinely show up in the company kitchen) to meetings works pretty well too .)
(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).
... In fact, Emily does not address the main discussion between Glenn and myself: where
should the documentation reside and how should it be maintained.
Sorry. Did not mean to duck the important questions. I hereby reiterate, attest and affirm that:
I believe that every piece of documentation that I am responsible for should reside and be maintained independently from the code. I have no problem checking it in and labeling it with a release number or a bug fix number. But the documentation I write is separate from the code. And, I believe, no tool will be capable of updating my docs automatically when code changes for long time to come.
Emily says she uses tools, but I infer she maintains all documentation
outside of the source code.
Yes, I use tools, but my tools are stone knives and bearskins compared to what some of you all have mentioned. And, yet, I'm content with these, my bare necessities (as long as I also have a LOT of RAM in my PC and a high resolution, very good quality screen, a very comfortable mouse, my comfy chair, and access to my text editor of choice as well as to Frame).
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 ;-)
Totally. Just don't listen to anything Walden, Glenn or I said and you'll be fine.
And, be careful out there.
--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.
Previous by Author:
RE: .php files
Next by Author:
Re: YOWZA--struck a nerve: Was Help API Documentation?
Previous by Thread:
RE: YOWZA--struck a nerve: Was Help API Documentation?
Next by Thread:
Re: YOWZA--struck a nerve: Was Help API Documentation?
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads