Date: Sat, 7 Nov 1998 21:39:33 +0000 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: "Jordan K. Hubbard" <jkh@time.cdrom.com>, Chad David <davidc@acns.ab.ca>, hackers@FreeBSD.ORG, doc@FreeBSD.ORG Subject: Documentation (was Re: freebsd-hackers-digest V4 #299) Message-ID: <19981107213933.43220@nothing-going-on.org> In-Reply-To: <12568.910468750@time.cdrom.com>; from Jordan K. Hubbard on Sat, Nov 07, 1998 at 11:59:10AM -0800 References: <3644A494.C40D3C8F@acns.ab.ca> <12568.910468750@time.cdrom.com>
next in thread | previous in thread | raw e-mail | index | archive | help
[ x-posted to hackers, where it started, and doc, where it should continue.
Reply-to set to doc]
On Sat, Nov 07, 1998 at 11:59:10AM -0800, Jordan K. Hubbard wrote:
> Yes, well, technical docs of this nature are definitely a job which
> requires that someone actively keep it up to date or it becomes
> rapidly worthless.
I know nothing about it, but what are people's thoughts on using some
sort of 'literate' programming system (is that the right term?) in
FreeBSD. After a day spent playing with TeX, the Web2c system is
obviously the nearest example.
Or maybe there's a C equivalent to JavaDoc?
As I say, I know nothing about these things, I'm just throwing it out
as a discussion point.
> Nik Clayton has just taken over as the new
> Documentation Project Manager (yea Nik!) and perhaps this is something
> he'd be willing to give you some bootstrapping assistance with.
Certainly. Ask and ye shall receive and all that. The -doc mailing list
is the general place to ask these sorts of questions (as Jordan has
indicated).
Take a look at
<URL:http://www.freebsd.org/~nik/primer/index.html>;
for my half-completed draft of a primer for contributors to the FreeBSD
documentation effort. I'm trying to get a critical mass of documents
together so that the learning curve is sufficiently shallow for most
people that they can just get stuck in documenting, rather than spending
time fighting with the toolchain.
> His
> early docs on coming to grips with SGML are already quite good and I
> imagine that the Docbook DTD could be used (or enhanced) to do
> programmer's API documentation just as well as the Handbook.
Absolutely. DocBook is designed for exactly that sort of technical
documentation. In fact, Someone on -doc recently made the suggestion
that we shift the manual pages from *roff format to DocBook. That's
possibly a touch too controversial at the moment, but might not be
beyond the bounds of possiblity for the medium term future.
In fact, it might be worth doing that within the Doc. Project, treating
them as another translation (similar to the Japanese translation) of
the manual pages?
See the (short) thread in -doc starting with a message from Christine
McKinty, <chrisb@odin.France.Sun.COM>, subject is
"FreeBSD manpages in SGML?", messageID is
<199811061532.QAA26783@odin.France.Sun.COM>.
> > depressing to joyfully congratulate myself for getting my first LKM
> > device driver to work, only to read five minutes later in Jordan's 3.0
> > announcement that LKM was dead.
>
> Sorry about that.. . Is it at least some consolation that what it's
> getting replaced with is a whole lot better? :)
It's also still useful. There are a lot of 2.2.x systems out there for
which it will be useful. And it can be added to a growing corpus of
sample documentation to point people to and say "Steal ideas from
this." :-)
> > Point me at what needs to be documented. I am only one person, but
>
> /usr/src/sys :-)
And pick a part of that, particularly if you're already familiar with it.
Better still, work out who's responsible for it (say, syscons, maintained
by Soren) and work with them. Ideally, you don't want them making large
changes without first working with you to make sure it stays documented.
This is one of my concerns with the Handbook at the moment. For example,
the section on how FreeBSD boots is getting more and more out of date
as -current progresses, and I don't know if anyone's stuck their hand
up to document it.
N
--
C.R.F. Consulting -- we're run to make me richer. . .
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-hackers" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19981107213933.43220>