From owner-freebsd-doc Thu Mar 19 02:21:12 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id CAA01259 for freebsd-doc-outgoing; Thu, 19 Mar 1998 02:21:12 -0800 (PST) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from tyree.iii.co.uk (tyree.iii.co.uk [195.89.149.230]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id CAA01253 for ; Thu, 19 Mar 1998 02:21:10 -0800 (PST) (envelope-from nik@iii.co.uk) From: nik@iii.co.uk Received: from carrig.strand.iii.co.uk (carrig.strand.iii.co.uk [192.168.7.25]) by tyree.iii.co.uk (8.8.8/8.8.8) with ESMTP id KAA23076; Thu, 19 Mar 1998 10:21:08 GMT Received: (from nik@localhost) by carrig.strand.iii.co.uk (8.8.7/8.8.7) id KAA13122; Thu, 19 Mar 1998 10:21:05 GMT Message-ID: <19980319102104.61658@iii.co.uk> Date: Thu, 19 Mar 1998 10:21:04 +0000 To: Annelise Anderson Cc: freebsd-doc@FreeBSD.ORG Subject: Re: doc "renovation" project volunteer References: <35104342.96EB950C@dal.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.85e In-Reply-To: ; from Annelise Anderson on Wed, Mar 18, 1998 at 06:20:25PM -0800 Organization: interactive investor Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org 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