Date: Thu, 30 Nov 2000 16:48:39 -0500 From: Michael Lucas <mwlucas@blackhelicopters.org> To: doc@freebsd.org Subject: troubleshooting tree revisited Message-ID: <20001130164838.A42727@blackhelicopters.org>
next in thread | raw e-mail | index | archive | help
(For those who missed earlier episodes, I'm working on a web-based problem resolution tree for FreeBSD.) Well, since I last brought this up I've been learning SGML and learning how the docs tree works. Meanwhile, I've been figuring out how to tackle this. I wanted to throw out some ideas and get them shot down before I go any further. :) jkh suggested a nice file that contained the decision tree, and that could be parsed to generate HTML. That's a great idea. I'm completely unqualified to do it properly. (I'm qualified to do it suckily, but I don't have time to make something that sucks.) If you're capable and willing to do this, please stop me now. Considerations: 1) long-term maintainable 2) can be handed over to the FreeBSD project when complete 3) I'm happy to do the work, but I'm opposed to extra work :) Ideally, we should only maintain each piece of information in one place; it will make long-term maintenance infinitely easier. That turns a troubleshooting tree into an index for the Handbook, FAQ, articles, and man pages. Unfortunately, the entries in the Handbook, FAQ, etc., are frequently "over the heads" of some of the users we're getting now. The entries also don't address how to troubleshoot or check some of these things. For example, I'm going to pick on http://www.freebsd.org/FAQ/admin.html#USER-FLOPPYMOUNT , simply because it's the question that finally made me snap and start this. Step 1 tells you to set the sysctl, but not how to check it. Later, you're told to create a directory, but not how to check the ownership. So, I have a few choices: 1) assume all readers are UNIX-literate, and abandon -questions to the current cesspool of ex-Windows folks who don't know how to help themselves. Makes the whole thing moot. Very maintainable, at least from the -doc point of view. 2) maintain a separate information tree. Pros: can do whatever the hell I want. Very poorly maintainable. 3) "dumb down" the Handbook and FAQ. Very maintainable. Downside: I would be hung by competent FreeBSD admins who just want to RTFM and get a quick answers. YMMV, but I think the downside is unacceptable, so I'm not going to do the work. 4) Add additional information as needed, but make it accessible through a "link" in the FAQ or Handbook (i.e., some sort of "beginners'" or "extra help" link). We could use conditional SGML compilation to keep this out of the print versions. Downsides: bloat. Lots more files. Plus I don't know how to set this up in the context of FreeBSD's build system -- I'd need to spend a while getting it to work, or get someone to set up one as an example. Very maintainable. Desirability: well, you folks have been maintaining -docs, you tell me. 5) Your miracle suggestion that will make all of this moot with almost no work whatsoever. Desirability: high. My preference is #4. Comments? Suggestions? Threats? Thanks, ==ml -- Michael Lucas mwlucas@blackhelicopters.org http://www.blackhelicopters.org/~mwlucas/ Big Scary Daemons: http://www.oreillynet.com/pub/q/Big_Scary_Daemons 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?20001130164838.A42727>