[Techtalk] Re: [Grrltalk] Documentation (was: Mandrake/Linux newbie deep in confusion about apache/advx)

[Meredydd Luff]

(keeping on techtalk as well, cause I'm not sure where this stuff should lie 
- maybe even on programming@?)

While this subject is under discussion, I'd like to stick my oar in:

A. P. I. Documentation.

One of the above words does not fit with the others. Why? For all the reasons 
Jenn just talked about. It's absolutely INFURIATING to pick up a powerful 
piece of code with a proper extensions mechanism and not have a clue how to 
do it. The same issues as for newbie Linux docs apply - even when they're 
there, existing API docs often assume a thorough knowledge of the inner 
workings of the program, which is something an API is specifically designed 
to *avoid* you having to know.

I try to document what I do, and keep it current, but I rarely if ever get 
any feedback, because any developer who (for example) wants to use my MSN 
library is not used to there being any API docs, and so has a severely 
atrophied RTFM instinct. If they even take the initiative to contact me and 
ask for help, I have to try and find a balance between being helpful for each 
individual case and just saying "the docs are in <directory> go read them!"
 
And so we're trapped - few docs are written because it's boring to do, and 
even if they *are* written, they're hardly ever read. They're not read 
because there generally aren't any...

OK, I'll stop fuming now, because it's not an issue I ought to be going red 
in the face about, but it irritates me a lot of the time. If anyone has the 
time and inclination to give me feedback on my documentation style (which I'm 
sure is far from perfect), check:

http://blackhole:81/msn/apidoc.php
http://www.everybuddy.com/eb-lite/ (both docs sections)

Meredydd

On Tuesday 22 October 2002 17:30, Jenn Vesperman wrote:
> This is a known issue with open source - and traditionally, with all
> software. The problem - as I see it - is that technical writing is seen
> as a low status field and as the most 'optional' aspect of writing code.
> An awful lot of programmers - particularly juniors - don't see any point
> to writing documentation. An awful lot of the rest don't know HOW to
> write documentation. And managers often treat documentation as an
> afterthought.
> How much commercial software comes with no useful manual?

-- 

MSN Developer, Everybuddy project
http://www.everybuddy.com/

MSN:     blip109 at hotmail.com
AIM:     blip109
Yahoo:   modula7