Date: Sat, 19 Jan 2002 20:01:20 -0500 From: Michael Lucas <mwlucas@blackhelicopters.org> To: Jim Mock <jim@FreeBSD.org> Cc: Chris Costello <chris@FreeBSD.org>, Murray Stokely <murray@freebsdmall.com>, doc@FreeBSD.org Subject: Re: splitting FAQ ch. 9 Message-ID: <20020119200120.A46175@blackhelicopters.org> In-Reply-To: <20020119220019.GA69416@helios.dub.net>; from jim@FreeBSD.org on Sat, Jan 19, 2002 at 02:00:19PM -0800 References: <20020117110921.B32325@blackhelicopters.org> <20020118030554.GC17795@freebsdmall.com> <20020118211213.J2208@holly.calldei.com> <20020119045555.GA57083@helios.dub.net> <20020119081751.A44161@blackhelicopters.org> <20020119220019.GA69416@helios.dub.net>
next in thread | previous in thread | raw e-mail | index | archive | help
Before we get into implementation details: I would like to suggest that after this discussion we create a "design specification" for the FAQ, the Handbook, and all other FreeBSD documentation. Once we reach a point where we all basically agree that the FAQ should have characteristics X, Y, and Z, let's document those goals so that this discussion doesn't happen again when FreeBSD 8.x goes -stable and it's time to re-revamp the doc structure. The FDP is an obvious choice for where to document them. Okay, now on to implementation details. On Sat, Jan 19, 2002 at 02:00:19PM -0800, Jim Mock wrote: > Well, that's one reason. We ripped all the 2.x stuff out of the > handbook a while back, and should probably do the same with the FAQ. If > somebody's been using FreeBSD long enough to still be using 2.x, I would > assume they have enough clue to keep it running. Fair enough. For the record, I think it would be desireable to keep old documentation on hand, but labeled "old". Even if it just sits in the Attic, it's still available for those who want to check out "The FreeBSD 5.X-6.X FAQ." > > I would suggest that we start a new FAQ with the release of 5.x, and > > call it "The FreeBSD 5.x FAQ." We could pull relevant info from the > > old FAQ into that. It could even be started now. > > This is reasonable. OK, barring further objection, let's just do it. :) > Well, part of the problem with that is that people don't seem to read > the FAQ either. It's just gotten too big, and if you don't know where > something is, you've got to look through the whole thing anyway. This is a definite problem. Some people we cannot help; if they won't read, too bad for them. Finding information in the FAQ is something that definitely concerns me. Better indexing and cross-referencing would help. > 14.3. I just upgraded to 2.0.5 and my tty0X are missing! How do I > solve this problem? That would be solved by creating the FreeBSD 5.x FAQ. And yes, a fiery death is too good for it. :-) > In order to make things easier to find, it would be extremely useful to > limit the questions asked to only the most frequent ones (like the damn > why'd I get -RC? question), and have the FAQ be one page only -- > questions at the top, answers at the bottom. Otherwise, as I mentioned > earlier, too much digging is needed if you don't know where things > already are. Hrmmm... Okay, point made. Let me throw out a counter-proposal. As a user, I don't want to go digging through the Handbook for a quick answer. Chances are the information I want is there, but is buried in the middle of an obscure discussion. Case in point: my recent FAQ addition on vnlru should be discussed in the Handbook, but it's going to be in the middle of a discussion on vnode management. As a user, I don't want to go wading through this whole chapter just to find out what that "vnlru shutting down" message during shutdown means. Also, I personally read the full documentation set once in the 2.1 days. (It wasn't really very good back then, sorry guys. :-) I read it again in the 3.X days. If I was Joe Average User, why would I re-read it to get an answer that wasn't in there last time? Should I constantly scan the docs to see what has updated? Nobody's going to like that. I therefore suggest that we have a "jumbo FAQ," that consists entirely of questions and pointers to answers. In fact, each question is simply linked to the correct section of the appropriate documentation. We put anchors in the appropriate spots in the HTML versions of the Handbook/articles/whatever. Someone can quickly scan this "jumbo FAQ" for what they're interested in, and immediately be redirected to the correct portion of the documentation. (The name "jumbo FAQ" sucks, but it's the most descriptive term I can think of.) This would address my main concern, but I'm certainly open to other suggestions and better solutions. ==ml -- Michael Lucas mwlucas@FreeBSD.org, mwlucas@BlackHelicopters.org my FreeBSD column: http://www.oreillynet.com/pub/q/Big_Scary_Daemons http://www.blackhelicopters.org/~mwlucas/ 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?20020119200120.A46175>