Date: Sat, 04 Dec 2004 12:19:16 -0500 From: Chuck Swiger <cswiger@mac.com> To: FreeBSD-doc@FreeBSD.org Subject: Re: Merging the FAQ -> handbook, build time options, proof ofconcept patch Message-ID: <41B1F194.6060807@mac.com> In-Reply-To: <20041203155837.572c9ece@localhost> References: <20041203125024.31182375@localhost> <Pine.LNX.4.44.0412031254480.24989-100000@pancho> <20041203155837.572c9ece@localhost>
next in thread | previous in thread | raw e-mail | index | archive | help
Hi-- I've been following this discussion with some interest and less angst, since my FreeBSD doc needs are generally satisfied. The Handbook compares well with high-quality docs such as Sun's AnswerBooks stuff. To be more precise in that comparison, the Handbook contains some very good writing and a relatively well-organized division of topics and chapters [1]; Sun's documentation is somewhat less creative in style, but is much more comprehensive in the detailed coverage of specific areas [2], and it also has a wider scope of organization. [3] ------ [1]: In particular, the Handbook is a noticably better read than the Solaris "System Administration Guide". [2]: Sun has the resources to produce 600+ pages just on the DiskSuite RAID software, or their Solstice Backup stuff, etc etc. [3]: See http://docs.sun.com. Note that it is gracefully multilingual, and the discussion in the help topics is worth a read (although buried too many clicks in). http://www.freebsd.org/docs.html or maybe http://www.freebsd.org/doc/en_US.ISO8859-1/books/ is the closest thing FreeBSD has to a "stable doc URL". Tom Rhodes wrote: > On Fri, 3 Dec 2004 13:02:12 -0600 (CST) > Mark Linimon <linimon@lonesome.com> wrote: [ ... ] >>I agree that we don't want any overlap in the FAQ and the handbook, >>or frankly for anyplace else for that matter. The overlap causes >>confusion for both users and doc committers. That's one of the >>reasons that the FAQ has rotted so badly. > > So, lemmie get this straight. > > Quick and question and answers in the faq, more thorough explinations > moved into the handbook? If you can't answer a frequent question with a paragraph or so, I would be happy if the FAQ gave a brief intro and a link to a more comprehensive description elsewhere. Whether elsewhere is in the handbook, some other article, or elsewhere on the web shouldn't matter. >>I see the FAQ serving as a "Start Here" document for people who >>are not familiar with FreeBSD; as a place for "what is it/why should >>I care/why did you do XYZ" thing. I see the handbook as "now that >>I have FreeBSD installed, how do I do XYZ". The timeslice I had to >>do the hackup job was insufficient to have gotten that across. > > Yes, I can see your point, valid it is. Heh. My take on this is that whenever someone answers a question on a mailing list with "This is a FAQ", such material actually ought to be in the FAQ. In particular, searching the FAQ either via the find mechanism in one's browser or via http://www.freebsd.org/search/search.html about an error like "ad0: WARNING - WRITE_DMA interrupt was seen but timeout fired LBA=2928095" produces nothing. Another example would be searching for "why does ruby dump core when I run portupgrade?"... [ ... ] > We need to close this matter and get back to work doing useful > and good things. So, we have one problem and we need to choose > what to do: > > Move most of the FAQ and keep the FAQ simple, > Move all of the FAQ and either have it all in the handbook or as 1 file, > Kill the FAQ off and start it a new. #1 seems to be the closest to my thoughts. I can't say I find the current FAQ to be very useful since it hides stuff too many clicks in and it doesn't reward searching especially well. I would be happier with a plain-text FAQ in Q&A format, or as a Docbook article rather than a book with subchapters. The sendmail FAQ and the INN FAQ struck me as good FAQs, in that they can be used successfully even to someone using less or i-search in Emacs on the ASCII version. Newer versions use a split HTML layout, but at least put all of the questions in one place that can be searched for easily. -- -Chuck
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?41B1F194.6060807>