Re: specifications

[jdd <jdanield@dodin.net>]

On jeu, 11 mai 2000, Greg O'Keefe à écrit

>If specifications were available in a clever format, perhaps some
>for of sgml (uml?) some documentation could be generated from it.
>As could tests. Specifications could be made for existing software,
>by reverse engineering, or they could originate from the ldp.

problem is that free software is often a vacation time effort and so
documentation is out of scope.

I have tried to work so as a documentation provider a couple of times. I
found that
*it's nearly impossible to make documentation from specifications, most
actors can't simply cope with the initials specifications: too hard, too
difficult or the right library not available, not enough time... and so
the final product is an other product than previously seen.
*most of the time the spécification don't go out of the programmers'mind.
Here the programmer is his own client, so no real spec necessity. To make
the project leader write down its mind, or simply speak about it 'for me
to write) is impossible. Usually I found myself workless, the programmer
making himself his doc.

But an idea calls an other... what we could propose should be:

"the Man page compagnon"

may be a man (ldp) as is an man (1) or a man (8).

everybody must have seen that man page are usually awfull, just a reminder
for somebody who kows already the facts.

couldn't we propose an additive to the man page with beginners survey and
learning example. This could be done with the original program author, but
not necessary and should be much more man page related than the actual
HOWTO.



-- 
<http://www.dodin.net> <mailto:jdanield@dodin.net>
QUI EST CET HOMME ? Aidez-moi à le retrouver
WHO'S THAT GUY ? Help me find him.
http://www.dodin.net/serge/index.html


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org