documentation

[David Johnson]

On Monday 27 August 2001 07:25 pm, Karsten M. Self wrote:

> As much GNU/Linux development
> happens outside the immediate auspices of the FSF, the old "GNU
> discourages man" gripe fails.

Since much of the userland and environment for Linux comes from GNU, GNU's 
attitudes towards man pages is particularly relevant. Even projects which are 
not under the GNU auspices frequently follow the GNU standards.

And here's what the GNU standards say (GNU Coding Standards):

"In the GNU project, man pages are secondary. It is not necessary or expected 
for every GNU program to have a man page, but some of them do. It's your 
choice whether to include a man page in your program. 

"When you make this decision, consider that supporting a man page requires 
continual effort each time the program is changed. The time you spend on the 
man page is time taken away from more useful work."

It sure sound to me like they're discouraging man pages! Don't write man 
pages because it will take away from your coding time, yet it's okay to write 
info pages.

I fully understand that developers hate writing documentation. I know this 
because I am a developer. But the fact remains that there is no one better 
suited to write *reference* documentation than the developer. And man pages 
are references.

Writing documentation is like changing diapers. It's a nasty smelly job, but 
you do it because you love your child.  If you love your software write the 
documentation, because finding someone who will write it for you at no charge 
is as difficult as finding someone to change your baby's diapers for free.

-- 
David Johnson
___________________
http://www.usermode.org