Re: YOWZA--struck a nerve: Was Help API Documentation?
It sounds to me that your experience has been unfortunate.
No, actually, I don't think my experiences have been unfortunate. I really enjoy my work and I'm told I do it extremely well.
However, I've worked with just as many who have come to realize that
detailed commenting is part of their job description, and needs to be
done. And that makes sense in an environment where people move from job
to job, or where many different people might be working on the code. Ina
couple of extreme cases, I've even seen companies unable to finish a
patch or revision because the code was commented and the only person who
understood it was on holidays.
I have been incredibly impressed with the high quality and skill and dedication of the programmers I've worked with recently. I believe they earn their salaries. I was not criticizing the comments they write. Most developers, in my experience, are extremely well-organized and more team-oriented than the stereotype would let most outsiders understand. No work is halted when personnel leave or call in sick.
However, in my experience, both as a developer and as a tech writer who reads programmer comments,
==> the comments that programmers write do not explain the API to the external user. The code does not explain the API to the external user. That's not the programmer's job.
Again, for me, documenting an API from code is like examining the cells on a whale's tail to try to figure out how the whale swims. It takes forever and it smells really bad and you get bogged down in details like, "How did the change in this wart's shape change how the whale swims? Or, did it?"
Comments in code are designed to explain to fellow-internal-programmers the particular decisions made in a particular code context. The specs and the plans and the external technical information is where the important stuff for API users should be, IME.
And, BTW, even if the code isn't commented, you can do a lot with it so
long as you have a testbed that you use to destruction. Even several
years ago, when my knowledge of code was even spottier than it is now (I
can change "Hello, World" to "Hello, Sailor" and that's about it :-) ),
I found that the best way to document parameters in the several hundred
applets with which I had to deal was to learn what lines of code defined
parameters, do a search for those lines in each applet, then play with
the parameter on a testbed until something happened. I reinstalled
several times, but the method was quicker than tracking down programmers
who kept irregular hours.
Not for me. I usually just send an email to the programmers which takes me 60 seconds, and I can send it any time, day or night. Then, I stop worrying about that issue, assume I'll get an answer back within a day or so and go on to other issues.
It takes even the fastest coder at least 60 seconds to make ANY code change, re-compile and run a test. And, given the state of the code that I document, I'd have to do hundreds and hundreds of re-compiles to get all my questions answered. Not time-efficient and more error-prone than just asking the expert. I prefer that my clients feel that I earn my hourly rate.
Furthermore, since I am generally writing the documentation while the API is being developed, there would be absolutely no way for me to just "try things out" and see what changes. My docs are usually due within days, sometimes hours, after the API code-freeze date so I don't have the luxury of trying various things out to resolve my questions about what particular parameters do. Oh, and about that comment -- I think Bruce made it -- about slight errors not being a problem. Well, most of the bugs reported against documentation at all the places I've worked, for groups of many, many tech writers -- the bugs in API docs are nearly ALWAYS -- there's this ONE STRAY or MISSING HYPHEN, ONE STRAY OR MISSING BRACE, SEMI-COLON, etc. Minor detail? Absolutely. Does it make code not work or not even compile? Absolutely. But if that detail is in a comment, the programmer's NOT going to notice.
Bruce, Glenn, Walden -- I'm going to duck out of this discussion now, because I do feel that maybe you've gotten to the point where you are claiming your methodology is better than mine.
From what I can tell there is no absolute Better in this particular process. It's clear to me that we deal with different levels of developer (yours are much less involved in the design process than the ones I deal with), we document different types of products, for different audiences (I almost always write API documentation for external developers who have few or no other sources of information about the product).
It sounds like documenting mostly from code, regardless of whether the docs are embedded in the code or external to it, works fine for your needs. Good for you. You have evolved a process that yields good results for you.
I'm also saying that a process like the one you describe would never, ever, ever work for the products I document.
Over and out.
--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.
References:
Re: YOWZA--struck a nerve: Was Help API Documentation?: From: Bruce Byfield
Previous by Author:
RE: YOWZA--struck a nerve: Was Help API Documentation?
Next by Author:
Intro to API
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