Feature Proposal: Create an online 'book' on Foswiki.org that facilitates discovery and use of existing documentation, and is suitable for making available in print form

Motivation

Whilst learning to:

• use and manage Foswiki;
• develop extensions for Foswiki; and
• develop a contrib for Foswiki,

I have sometimes had difficulties finding relevant documentation and/or re-finding documentation I know exists. This proposal would reduce such issues.

Description and Documentation

In addition to the standard documentation shipped with Foswiki by default, Foswiki.org contains a wealth of information for users, administrators and developers. However, I have found this documentation to not always easily discoverable; despite often browsing F.o, I still find myself unsure as to whether or not documentation exists on a certain subject, and even when I am sure, have difficulties remembering where it was located. Further, in the case of the latter, making use of search facilities has not necessarily helped me find what I'm after.

Proposals have been made for a Foswiki book and a search query cookbook; the former resulted in the creation of Foswiki At Work. However, progress on these things appears to have stalled.

This proposal seeks to address all the above issues simultaneously.

A 'Book' web could be created on F.o with contents along the lines of (in emacs org-mode format):

* Book
** Part 1 - Setup and use
*** Introduction
**** To wikis
**** To Foswiki
*** Installation
**** OS platforms
     [f.o/Support/InstallingOnSpecificPlatforms]
***** Windows
***** Linux
***** Mac OS X
**** Web server platforms
***** Apache
***** FastCGI
***** IIS
***** nginx
**** Hosted platforms
     [f.o/Support/InstallingOnSharedHosts]
*** Configuration
**** Security
***** [f.o/Support/SecurityFeatures]
***** [f.o/Support/SecuringYourSite]
***** [f.o/Support/ProtectingYourConfiguration]
***** Access control
**** Internationalisation
     [f.o/Support/InternationalizationSupplement]
*** Best Practices
    [f.o/Support/BestPracticeTips]
*** Misc
**** Macro quoting
**** Personal preferences page
**** Backups
** Part 2 - Cookbook
*** SEARCH queries
*** FAQ
*** Performance 
    [f.o/Support/PerformanceSupplement]
*** Scenarios
**** Foswiki at home
***** Personal Information Manager
**** Foswiki behind a firewall
***** Team Information Manager (TIM)
***** Project tracking and reporting framework
***** Meetings and Minutes
***** Building forms
***** Integrating with Email
***** Foswiki as a data source for specialist applications
** Part 3 - Foswiki development / Plugin development
*** Plugin development
*** Contrib development
*** Foswiki development
** Part 4 - Reference
*** Preferences
*** Macros
*** API

(Text in square brackets describes an existing page that could be either INCLUDEd or linked to directly.)

This would:

• create a single location to which people can be pointed to find existing information on F.o;
• assist in identifying gaps in existing documentation;
• combine existing book proposals;
• allow for the creation of one or more treeware books (e.g. each 'part' listed above could be a separate 'volume') via BookmakerPlugin / PublishPlugin.

Examples

Impact

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

-- Contributors: AlexisHazell - 09 Aug 2012

Discussion

You probably want to take a look at BookmakerPlugin and PublishPlugin which together achieve what you want (i.e. producing a printable copy plus full stand-alone HTML)

The most recent improvements support the generation of a single monolithic static HTML document; this is then searchable using ctrl+F in browsers, so is quite attractive to some users.

-- CrawfordCurrie - 09 Aug 2012

Yes, sorry, I should have mentioned in the proposal that BookmakerPlugin / PublishPlugin could be used to create the printable copy; I'll change that now.

-- AlexisHazell - 10 Aug 2012

Three years have passed. Changing this to a Parked proposal. Needs someone to adopt it.

-- GeorgeClark - 19 Nov 2015

Commenting is disabled while not logged in