Date: Wed, 30 Jun 1999 22:38:16 -0600 From: Wes Peters <wes@softweyr.com> To: Terry Lambert <tlambert@primenet.com> Cc: Jesus Monroy <jesus.monroy@usa.net>, seth@freebie.dp.ny.frb.org, advocacy@FreeBSD.ORG Subject: Re: [Re: [Re: [Re: [Re: [Re: My FreeBSD Experience ]]]]] Message-ID: <377AF0B8.9076225F@softweyr.com> References: <199906302330.QAA10390@usr09.primenet.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Terry Lambert wrote:
>
> Jesus Monroy wrote:
>
> > Currently, errors in the documentation are constantly
> > creeping in because fixes (or changes) are made
> > to the base utility set, or the parts they
> > use (ie. command-line flags).
Errors in the documenation are constantly creeping in because that is
just how the world works. You can be a part of the problem, or a
part of the solution. To be a part of the solution, feel free to
submit re-written man pages, new man pages, or just diffs.
> > Where is the root of the problem? I don't know.
> > Can this be solved? I don't know.
> > Well this problem continue to manifest itself
> > at irregular times and without warning?
> > Yes, it's a real daemon.
>
> It's possible to resolve. The engineering technique is called
> "literate programming". There was apparently a nice talk about
> it at Usenix, with someone building a kernel using the technique
> to allow them to publish an example.
JavaDoc does a somewhat credible job along these lines as well. Wind River
systems, the makers of the VxWorks embedded OS, also uses an internal
documentation format so the man pages are maintained in the source files.
None of these are as complete as Web, the literate programmin tool, which
embeds the code within the documentation, but all are at least steps in
the right direction.
Encouraging programmers to update the documentation as they update the
code is a step in the right direction, too.
--
"Where am I, and what am I doing in this handbasket?"
Wes Peters Softweyr LLC
http://softweyr.com/ wes@softweyr.com
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-advocacy" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?377AF0B8.9076225F>