Date: Thu, 19 Mar 1998 10:21:04 +0000 From: nik@iii.co.uk To: Annelise Anderson <andrsn@andrsn.stanford.edu> Cc: freebsd-doc@FreeBSD.ORG Subject: Re: doc "renovation" project volunteer Message-ID: <19980319102104.61658@iii.co.uk> In-Reply-To: <Pine.BSF.3.96.980318181025.10998A-100000@andrsn.stanford.edu>; from Annelise Anderson on Wed, Mar 18, 1998 at 06:20:25PM -0800 References: <35104342.96EB950C@dal.net> <Pine.BSF.3.96.980318181025.10998A-100000@andrsn.stanford.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, Mar 18, 1998 at 06:20:25PM -0800, Annelise Anderson wrote:
> --I don't think there's any vision of what FreeBSD documentation
> ought to look like in, say, a year or two...maybe the manual pages/FAQ/
> handbook/other stuff as needed is okay, then again maybe before a lot of
> work is done we ought to consider where we would like to go (Jordan has
> a MiniFaq on Usenet)
In general, I agree.
Damn, I need to stop reading this stuff at work.
I think we need to recognise that different people expect different things
from the documentation. Those at the beginning of the learning curve need
more 'hand-holding', more examples and more explanations than those who
are familiar with 'the Unix way of doing things'.
Some people just want short FAQ lists, so they can get to the meat of
the solution to whatever problem they're having and solve it quickly.
Still others want to understand why you need to do x, y and z in order
to get something to work.
About the only thing that links these documents is the task they describe.
For example, "Setting up PPP" can probably be split into
- The PPP FAQs
- A PPP Quickstart/tutorial
- PPP in depth
Right now, those three roles are split between the FAQ, the tutorials and
the Handbook.
I'd like to see (and this is some months away, believe me) a system where
by all these things are suitably marked up. The documentation build process
can then be automated.
This gets to the point where the documentation builder can
- Run one command, and all the FAQs from all the topics are collated
and built. The result of this is called "The FreeBSD FAQ".
- Run another command, and all the quickstart tutorials are collated
and built. The result of this is called "The FreeBSD tutorials".
- Run yet another command and all the in depth stuff is collated and
built. This is called "The FreeBSD Handbook".
- Run still another command and get the "Everything you need to know
about PPP" documentation set, which consists of the FAQs, the
tutorials and the Handbook.
and, naturally, the result of this process will be available in HTML,
plain text, RTF, Postscript, PDF. . .
Thinking about this some more, there are other categories as well. For
example "All the e-mail that's been sent to -questions about PPP" is one
of them.
In essence, I think you need to view all the documentation resources about
FreeBSD has a homogenous lump that can be manipulated and extracted in
different ways.
Right now, we don't have that.
> --It seems to me that one useful feature of a documentation system
> in this rapidly changing world would be a way to manage multiple documents
> from different sources (e.g., documents or articles mailed or saved to a
> file from Usenet, mailing lists, web pages, ftp sites) that may relate to
> the same topic. (I have a pretty good way to do this in dos but nothing
> really equivalent in unix....at least not that I know of.)
How do you do this in DOS?
> --There seems not to be anyone in charge, who functions as the
> interface between the core team and the rest of the world and has enough
> authority to make some decisions.
What sort of decisions?
> --The one part of the whole documentation project that seems to
> have direction and make progress is the uh, what do you call it, creating
> documents in sgml and being able to produce them in any other format.
> This is going well, but it's only one piece of the puzzle (although an
> interesting one).
For me, that's because
- It relates to a part of what I do in my day job, so I can be learning
about it in 'fun' context as well as a 'work' context.
- I'm weird enough that I find this kind of thing intellectually
stimulating anyway.
- Having the information in a usable form is a pre-requisite for being
able to do useful things with it.
After I've got the conversion process nicely automated I expect to be able
to turn more of my attention to the fun stuff outlined above.
N
--
Work: nik@iii.co.uk | FreeBSD + Perl + Apache
Rest: nik@nothing-going-on.demon.co.uk | Remind me again why we need
Play: nik@freebsd.org | Microsoft?
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19980319102104.61658>