After some thinking, I've decided to break out the documentation from the
source tree and start up a separate CVS module for it. This because a) the
documentation never keeps up with the code anyway, b) I expect to expand
the documentation into a more complete set of instruction manuals, and c)  
the documentation takes up an disproportionally large part of the
file-size of the download tarball.

Further, the documentation efforts will be concentrated on supporting the 
3.2.x branch. The 3.0.x branch already has sufficient although somewhat 
brief documentation while 3.2.x has almost none. 

Because I'm perverse, I've spent a couple of days during the xmas vacation 
thinking up a structure for the documentation, and started to write parts 
of it. I'm planning on splitting up the documentation in four major 
documents:

* "Mod_Survey for Beginners", an introductory manual with step-by-step 
  instructions on how to write survey files.
* "Mod_Survey Syntax Reference", a no-nonsense list of tags and parameters 
  with short descriptions. Will also describe syntax for extra html
  markup and dynamic contents
* "Mod_Survey SysAdmin Guide", thorough instructions for installing and
  maintaining a Mod_Survey installation. Will also include guidelines
  on security and similar.
* "Mod_Survey Programmer's Guide", a thorough explanation of the code
  structure and instructions on how to go about common programming
  tasks such as adding a new parameter, a new tag or a new translation.

This may sound a bit ambitious, but I make no promises as to when all this 
will be finished. The first two will likely be finished before summer, 
since I intend to use them as course literature on a summer course on web 
questionnaires in july.

So far I've written outlines of all the documents, and some parts of the 
syntax reference. I'm adding the outlines below, in the hope that someone 
will come up with suggestions for more sections, or perhaps at least some 
general cheering. 

Also, I will eventually need volunteers for checking up on facts and 
language, but that's some time off.

*** MOD_SURVEY FOR BEGINNERS ***

Cover (Front page, text license...)
Index
Foreword
Introduction
  What is a web questionnaire?
  What is Mod_Survey?
  Terminology
About Mod_Survey
  A brief history
  What does Mod_Survey support?
  What does Mod_Survey *not* support?
  Different versions of Mod_Survey
  Comparing Mod_Survey with other systems
  How to get access to Mod_Survey
Basic working with survey files
  Requirements
  The life span of a survey
  Writing a survey file
  Uploading the survey
  Accessing the survey
  Administrating the survey
  Downloading data
Writing questions
  What is a question?
  Static lead-in texts
  Closed single-choice questions
  Multi-choice questions
  Open questions
  Scales
  Matrices
  Designing custom question types
Collecting automatic data
  Non-visible "questions"
  Inserting constant values
  Fetching data from the environment
  Date, time and timing
Restricting access
  Setting up user files
  Access levels
  Managing respondents and unique answers
Color and decoration
  Themes
  Stylesheets
  Global layout settings
  Extra HTML markup
  Graphics
Surveys with more than one page
  Unbranching multipaging
  How variables are handled
  Conditional branching with IF
  Conditional branching with CASE
  How to fail miserably with a branching survey
Dynamic contents
  Linking to external files
  Inserting data from answers
  Perl snippets
Using databases
  Why would you want to use a database?
  Setting up DBI
  Syntax and tweaks for DBI
  Letting repondents delay answering
Downloading and using survey data
  The data module
  The HTML export
  The SPSS export
  ...
  Importing data in Excel
  Importing data in Access
  Importing data in SPSS
Acknowledgements
  About the author
  People who contributed to Mod_Survey
Appendix 
  Short installation instructions
  Migration guide for 3.0.x users
  The GNU General Public License

*** MOD_SURVEY SYNTAX REFERENCE ***

Cover (Front page, text license...)
Index
Introduction
  Tags
  Markup
  Snippets
Configuration tags
  SURVEY
  SECURITY
Visible variable-carrying tags
  BOOLEAN
  CHOICE
  CUSTOM
  LIST
  LICKERT
  MATRIX
  MEMO
  TEXT
Invisible variable-carrying tags
  CONSTANT
  DATETIME
  ENV
  TIMER
Tags related to multipaging
  CASEROUTE
  IFROUTE
  ROUTE
  SEQUENCE
Layout-related ans other tags
  NEWLINE
  COMMENT
Extra HTML markup syntax
  Colors
  Font styles
  Graphics
  Special characters
  Custom html
Dynamic content
  Including external files
  Referencing previous variables
  Perl snippets

(Presentation files)

*** MOD_SURVEY SYSADMIN GUIDE ***

Cover (Front page, text license...)
Index
Introduction
  What is covered?
Getting the latest version
  Different branches
  Tarball
  CVS
General installation guidelines
  Before starting installation
  Apache 1 or Apache 2?
  System, software and library prerequisites
  Recommended system
  Should we use windows or a sane server OS?
Semi-automatic installation
  The installation script
  ...
Manual installation
  Copying files
  File and directory permissions
  Getting a survey.conf
  Editing httpd.conf
Platform-specific installation notes
  Windows
  MacOSX
  Solaris
  OpenBSD
System and configuration files
  Additons to httpd.conf
  survey.conf
  startup.pl
  Survey
  data
  webroot
  Lang
Security
  Mod_Survey's security policy
  Keeping track of security announcements
  Authentication and authorization
  System integrity
  Data integrity
  Exploitability of dynamic contents
  Known areas that need improvement
Maintainence
  Necessary central administration
  Upgrading to a new minor version
  Upgrading to a new major version
How-to for common administrative issues
  Making sure mod_perl is installed and working
  Maintaining several mod_survey versions on the same machine
  Restricting surveys to one directory
  Backing up data
  Cleaning out old data
  Setting up a cron job for dead keys

*** MOD_SURVEY PROGRAMMER'S GUIDE ***

Cover (Front page, text license...)
Index
Introduction
  Hierarchical code overview
  The life-span of a survey
Code issues before and during start-up of the system
  installer.pl
  survey.conf
  startup.pl
Request phase, session and arguments
  Handler.pm
  Argument.pm
  Session.pm
  Authentication.pm
Parser and document
  Document.pm
  System.pm
  Object.pm and common tag structure
Display
  Display.pm
  Multipaging
Data
  Submit.pm
  Data.pm
  DataEntry.pm
  The export modules
Misc and deprecated modules
  Admin.pm
  Statistics.pm
Presentations
  ...
Internationalizations
  Good and bad with PGetText
  The language files
How-To and checklists for common programming tasks
  Adding a parameter to a tag
  Adding a completely new tag
  Writing a new data export
  Making sure new modules get installed
  Adding new dynamic-content markup
  Writing a translation
  Compiling a modified translation file
Commiting code for fame and glory
  Code style and recommendations
  Keeping up-to-date with CVS
  Making a patch
  Sending in a patch for merging
  Getting CVS write access
  Writing documentation

// Joel
Skickat av Joel Palmius <joel.palmius <at> mh.se>
till survey-discussion