From owner-freebsd-doc Mon Jul 1 22:36:44 1996 Return-Path: owner-doc Received: (from root@localhost) by freefall.freebsd.org (8.7.5/8.7.3) id WAA28903 for doc-outgoing; Mon, 1 Jul 1996 22:36:44 -0700 (PDT) Received: from freenet.hamilton.on.ca (main.freenet.hamilton.on.ca [199.212.94.65]) by freefall.freebsd.org (8.7.5/8.7.3) with SMTP id WAA28894; Mon, 1 Jul 1996 22:36:42 -0700 (PDT) Received: from james.freenet.hamilton.on.ca (james.freenet.hamilton.on.ca [199.212.94.66]) by freenet.hamilton.on.ca (8.6.12/8.6.12) with ESMTP id BAA03010; Tue, 2 Jul 1996 01:36:31 -0400 Received: (ac199@localhost) by james.freenet.hamilton.on.ca (8.6.12/8.6.12) id BAA12753; Tue, 2 Jul 1996 01:38:07 -0400 Date: Tue, 2 Jul 1996 01:38:06 -0400 (EDT) From: Tim Vanderhoek To: "Julian H. Stacey" cc: Tim Vanderhoek , doc@FreeBSD.ORG Subject: Re: share/doc/FAQ/obj/freebsd-faq.html In-Reply-To: <199607012139.XAA19679@vector.jhs.no_domain> Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-doc@FreeBSD.ORG X-Loop: FreeBSD.org Precedence: bulk On Mon, 1 Jul 1996, Julian H. Stacey wrote: > Well, rather minority /strange, but the answers have zero value, > except as humour, where perhaps a dave barry chunk outside FreeBSD `du' space > might be more appropriate reading :-) > Part 2 of Q7.21 could even have a sensible answer, but hasnt. I recall, when reading the FAQ for the first time before installing FreeBSD seeing the answer to the `temperature' question and having spend 5-10 minutes wondering exactly how serious it was... Having gone through that experience, I can say that I appreciate the value of a ridiculous question & answer in the FAQ. I found it helped take away the "scariness" of installing a foreign OS onto my machine. Not as importantly, I think it can also encourage people to read more of the FAQ. ("What the heck is that question about!?!" "Hmm... well, I've read one question now, I might as well read another"). > > > Reorder the words in the FAQ sections titles, > > > similar to the way a stores list of engineering components is listed, > > > so that the index is visually scannable fast & easily. EG: > > > Printer, colour, driver: fails when blah blah > > > Printer, postscript: filters available > > > Printer, parallel port: interrupt config > > > Printer, serial: interface parameters > > > In concept they're the same logical structure, > just that mine would present more info per page, > which would be nicer over a slow web link > than if we only have a few items per sub index, > + your struct wouldn't be so usefull when it comes to printing the whole FAQ; > however either way would be an improvement for screen interactive usage. Good point. I think what scares me about what you first suggested is the lack of a nice approachable sentence. At one end is the fact that having a large multi-line description of the question would take away the organizational value of the above; at the other end there is a certain amount of readability and style necessary. Anyways, I withdraw my suggested structure. :) Other things, though... In the answers themselves. I question the usefulness of having a "Previous" and "Next". Often, even with the best of organized hierarchies, I suspect that no two questions will be related in this "Previous"/"Next" manner. Rather, each answer should have a short list of cross-references at the end that may also help the reader with their problem. I realize this is a function of the linuxdoc sgml, but there has been some more talk lately about replacing it, I think... Each answer should have, at the top, in a consistent place, a date-modified field, and a field saying what release a given answer does or does not pertain to. Since the index entry, or "question" for a given answer will be fairly curt, it could be worthwhile rewriting the question in a more descriptive (maybe even colloquial) manner as part of the answer. Things like this are fairly easy compared to deciding on a nice & neat hierarchy, though. > > I look at the INDEX for the FAQ, and I'm scared... It's ugly... :( > > Yes. It's ugliness will discourage use as an index, > & so people will be tempted to post Q instead. It'd be one more reason to choose...yunnoo...well...something else over FreeBSD. And, of course, that's no good! :) -- Outnumbered? Maybe. Outspoken? Never! tIM...HOEk