From owner-freebsd-doc  Wed Jul  3 20:41:08 1996
Return-Path: owner-doc
Received: (from root@localhost)
          by freefall.freebsd.org (8.7.5/8.7.3) id UAA24138
          for doc-outgoing; Wed, 3 Jul 1996 20:41:08 -0700 (PDT)
Received: from gatekeeper.fsl.noaa.gov (gatekeeper.fsl.noaa.gov [137.75.131.181])
          by freefall.freebsd.org (8.7.5/8.7.3) with ESMTP id UAA24128;
          Wed, 3 Jul 1996 20:41:04 -0700 (PDT)
Received: from emu.fsl.noaa.gov (kelly@emu.fsl.noaa.gov [137.75.60.32]) by gatekeeper.fsl.noaa.gov (8.7.5/8.7.3) with ESMTP id DAA28061; Thu, 4 Jul 1996 03:30:50 GMT
Message-Id: <199607040330.DAA28061@gatekeeper.fsl.noaa.gov>
Received: by emu.fsl.noaa.gov
	(1.40.112.4/16.2) id AA068951051; Wed, 3 Jul 1996 21:30:51 -0600
Date: Wed, 3 Jul 1996 21:30:51 -0600
From: Sean Kelly <kelly@fsl.noaa.gov>
To: jfieber@indiana.edu
Cc: fdocs@jraynard.demon.co.uk, roberto@keltia.freenix.fr, jhs@freebsd.org,
        hoek@freenet.hamilton.on.ca, doc@freebsd.org
In-Reply-To: 
	<Pine.BSF.3.94.960703163150.8040F-100000@Fieber-John.campusview.indiana.edu>
	(message from John Fieber on Wed, 3 Jul 1996 16:35:49 -0500 (EST))
Subject: Re: share/doc/FAQ/obj/freebsd-faq.html
Sender: owner-doc@freebsd.org
X-Loop: FreeBSD.org
Precedence: bulk

>>>>> "John" == John Fieber <jfieber@indiana.edu> writes:

    John> If you have any thoughts about what the ideal
    John> structure for the killer FAQ would be, let me know!

Hmmm ... I like Bresler's engineering-style suggestion

   Printing; setup; help with /etc/printcap file
   Printing; problems; printing works but is slow
   Printing; problems; no output
   Printing; problems; stair-case effect

which might suggest something akin to

   <faq>printing
     <faq>setup
       <faq>help with /etc/printcap file
	 <answer>See the handbook section on Printing for complete
	   information on setting up your /etc/printcap file.
       </faq>
     </faq>
     <faq>problems
       <faq>printing works but is slow
	 <answer>Change the lpt driver from interrupt to polled mode.
       <faq>no output
	 <answer>Check the /var/log/lpd-errs files.  If you see ...
       <faq>stair-case effect
	 <answer>Adjust the printer with a blunt instrument ...
       </faq>
     </faq>
   </faq>

Of course, this is letting the output drive how the SGML looks, which
shouldn't be the case.  Still, marking up categories would help
organize the material and such an organization could have a totally
different presentation than in the example above.  And that solves the
main problem with most FAQs: organization.

-- 
Sean Kelly                          
NOAA Forecast Systems Laboratory    kelly@fsl.noaa.gov
Boulder Colorado USA                http://www-sdd.fsl.noaa.gov/~kelly/