[Sigia-l] Collation of faq responses

[Karl Fast]

> About a week or so ago I asked folks to help me out with some issues
> around FAQs--the rest of this message is the responses I got.


One thing that just triggered with me is the Perl Cookbook, which is
very FAQ-like, and the single best programming book I have ever
used. It might make a useful model for documentation that is kinda
FAQ-like, but also kinda reference-manual-like.

   http://www.oreilly.com/catalog/cookbook/

The book is divided into chapters, each on a different programming
topic (strings, files, databases, pattern matching, etc.)

The chapter has an introduction to the topic. This is followed by a
series of common problems for that topic area. The problems get more
advanced as the chapter progresses.

For example, the chapter on File Contents looks like this:

  8. File Contents 
      8.0. Introduction   273
      8.1. Reading Lines with Continuation Characters 
      8.2. Counting Lines (or Paragraphs or Records) in a File 
      8.3. Processing Every Word in a File 
      8.4. Reading a File Backwards by Line or Paragraph 
      8.5. Trailing a Growing File 
      8.6. Picking a Random Line from a File 
      8.7. Randomizing All Lines 
      8.8. Reading a Particular Line in a File 
      ....
      
Each problem is then broken down into four parts:
  
   Title
   Problem statement (a few lines)
   Solution (code that solves the problem with minimal explanation)
   Discussion (a detailed explanation of the code, alternate
      solutions, things to watch our for, related recipes, etc.)

See the sample chapter to get a feel for this:

  http://www.oreilly.com/catalog/cookbook/chapter/index.html
      
I looove this book. It might make a good structure for a help manual
that is FAQ-like without being a FAQ.

As an aside, I'm now learning Python (love it). I have the Python
cookbook, which is good and darn helpful, but it's not as good as
the perl book. I still use the perl cookbook for some things and
then translate it to python. 


--karl