Date: Mon, 23 Mar 1998 16:37:49 -0800 (PST) From: Annelise Anderson <andrsn@andrsn.stanford.edu> To: nik@iii.co.uk Cc: freebsd-doc@FreeBSD.ORG Subject: Re: doc "renovation" project volunteer Message-ID: <Pine.BSF.3.96.980323152259.11519B-100000@andrsn.stanford.edu> In-Reply-To: <19980319102104.61658@iii.co.uk>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, 19 Mar 1998 nik@iii.co.uk wrote: > 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. Yes, I agree. > > 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. I think this sounds great; I agree. In addition to the resources we can name, there's likely to be stuff collected via mail messages, newsgroups, and web surfing. > > > --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? I do it with a program Lotus sold between about 1989 and 1993, called Magellan (not the same as the search engine by that name). Basically Magellan indexed files it was told to index (skipping *.exe and the like if asked to do so). The index could be searched and would very quickly provide a file list in a left-hand column and the text of the document on the right. It was then possible to search for (other) specific text or go through the documents rather quickly using the arrow key. It was furthermore (and this was/is important to me) possible to mark text and send it to a new file (and append to that file). It furthermore had viewers for major software formats, so it could index and correctly display word processor files, spreadsheet files, etc., and even gifs. I'm not sure why Lotus quit updating it and selling it--perhaps because it does in fact have limits; it really is a dos program that doesn't use memory above 640k (at least not above 1 meg). It thus can't handle more than about 10,000 (maybe 12,000) files and a gigabyte or so of data, which for me is beginning to be a limitation. Once the index is built (and you can build as many as you like), it's very fast, much faster than glimpse. Glimpse with a front end that actually views files would be a comparable setup. Glimpse is sort of slow when a moderate size drive (e.g., 1.6 gigabytes) has been indexed, but what it really needs is the front end. > > --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? Overall direction, who's going to do what, what the priorities are. E.g., is it desirable to develop Linux-style "how-to" documents that might, in certain areas, cross-cut these other resources discussed above? One area where a cross-cutting "how to" might be worthwhile is samba. There's some role for overall policy-setting (yes or no to linux-style how-to's; if no maybe yes to something else) and keeping track of volunteers or even actively recruiting people on specific topics. Another kind of decision is the review/publication decision--is a particular document ready for prime time, does it need review, if so how does it get reviewed? (All the while taking account of the fact that all the people involved are volunteers.) > > --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. > It sounds very interesting. Annelise 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?Pine.BSF.3.96.980323152259.11519B-100000>