Date: Mon, 27 Dec 1999 19:28:29 -0800 (PST) From: dhesi@rahul.net (Rahul Dhesi) To: freebsd-stable@freebsd.org Subject: Re: bugs in the handbook. (FreeBSD Portal) Message-ID: <19991228032829.4006D24E@waltz.rahul.net> References: <freebsd-stable.XFMail.19991223212645.cwass99@home.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Colin <cwass99@home.com> writes:
>1) The peole who know enough about the system to document it properly
>generally don't have the time (or inclination...gotta love those
>programmers ;)) to spend on documentation. They're too busy fixing the
>problems that turn up regularly or adding enhancements (which is where
>most of the problems start ;)).
It doesn't take very long to write quick documentation. It's polishing
it that takes time. The developers have the time to write quick
documentation, if they will embed in the source code in the form of
structured comments. This can be then taken and polished by others.
>2) The peole who are most willing to spend time on the documentation
>don't have the specific knowledge to do it. They are the one's who
>would like to be reading the docs.
This is true.
Notice how perl modules seem to be quite well documented? It's partly
because the documentation is embedded in the source. When the
maintainer updates the source, it's relatively easy to udpate the
documentation at the same time...it's in the same file and the
maintainer has (by embedding the documentation in the same file)
implicitly accepted responsibility for keeping it updated.
FreeBSD separates the documentation from the code. Thus somebody
writing code has no explicit or implicit responsiblity for keeping the
documentation updated.
--
Rahul Dhesi <dhesi@spams.r.us.com>
See my UUNET spam mini-faq at:
http://www.rahul.net/dhesi/uunet.faq.txt
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-stable" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19991228032829.4006D24E>