Feature Proposal: A community-written book


I run a Foswiki installation here at work but I do find it difficult to provide a simple yet consise overview of the application. It would be hugely beneficial to be able to purchase a book which would cover the basics of what a Wiki is and how powerful Foswiki has become.

A book would be an excellent way of promoting Foswiki in the public eye. It would also provide an ISBN, which would help our "notability" case on wikipedia. i believe even one book is sufficient. perhaps some form of print on demand can give us the ISBN we want, without having to convince a traditional publisher.

It could also raise vital funds for the association, though unless you have a blockbuster, most book authors don't really make much money; it's truly a labor of love. non-traditional outlets such as on demand book printing might provide a larger source of income, but that should be hoped for, and would be a happy occurrence should it come to pass, but don't expect it.

Description and Documentation


  1. what is a wiki?
    • why foswiki?
  2. cookbooks
  3. organizing your data
  4. sample wiki applications
  5. create personalized skins
  6. best practices
  7. website gallery
it's hard to break this down into a list; everything is deeply intertwingled. wink regardless, the focus should be for a well-written, concise introduction with the majority of the content towards enabling beginning users to becoming intermediate users.

after relevant entries, there can be "call out" boxes which tell people how they can get involved and direct them to the appropriate place(s) online.



A single ISBN costs US $125; a block of 10 costs US $275 through the "standard" organizations. cheaper alternatives exist from various other sources, including for free when publishing via lulu.com.



-- Contributors: PadraigLennon, WillNorris - 13 Jan 2010


I fully support this initiative. This is a chance to fundamentally rewrite our documentation to user level. To make it more about solving problems than about how the action links look like (just one example).

I find the setup of http://book.realworldhaskell.org/read/ useful - they opened up the 'book' long before it was published, and had many updates on their blog. The inline comments are very useful as it allows to read the chapters without going back and forth, and check out those comments on sections you are interested in.

-- ArthurClemens - 13 Jan 2010

Me too. My gut tells me it'll take someone to "lead" on the book, and set a clear direction, otherwise it'll become as uneven and fragmented as the documentation set. We have to beware of trying to create a book that is all things to all men!

As well as the "blood and guts" proposal above, I'd like to suggest another approach. We all know how Foswiki can be something different to each person who uses it, and that some people have difficulty seeing the forest because of all the trees blocking the view. So a text that is organised as a set of "use cases" showing how Foswiki is used by people with different skill sets could be very useful. For example,

  1. Personal Information Manager
  2. Project Tracking and Reporting framework
  3. Corporate web framework
  4. Public collaboration site
  5. Knowledge management
  6. etc.
Each user story could be illustrated by experiences drawn from a number of different people and sites. And the stories should contain sufficient detail to help someone implement the story in their own wiki.

Whatever we decide, I would be quite happy to help out non-native English speakers with proof editing.

I started FoswikiAtWork for this book.

-- CrawfordCurrie - 14 Jan 2010

This would be cool to do as a community project! I always wanted to write up on wiki-apping. However, as Crawford already said, this is somewhat different for a lot of us and we as a community are not very good in agreeing on a common guide. Still people are in desperate need to get some best practices told before they start. All to often I heard "wow, I whished we knew that half a year ago. now we need to reorganize a lot." So while a use case oriented approach is a joy, such a book will also need some chapters on the fundamentals and a "putting the bits together" kind of code of practices.

-- MichaelDaum - 14 Jan 2010

I agree that this initiative requires a "main author" to maintain the coherence of the book, or at least to maintain the drive. I would not mind if at least half the money from the book goes to that "main author", at least to compensate the effort.

I see there is room for more than one book:

  • Foswiki in a nutshell
    • what is a wiki?
    • why foswiki?
    • Basic concepts
      • webs & subwebs
      • Topics
      • Online editing
      • attachment
      • versioning & Auditing
      • Foswiki Syntax (FML?)
      • Macros
      • Extensions
    • Installing & Configuring Foswiki
    • Organizing topics
    • Skining Foswiki

  • Advanced Foswiki
    • Creating Foswiki application
    • Customizing Skins
    • Creating Extensions
      • Creating Plugins
      • Creating Contribs
      • Creating Skins

  • Foswiki recipes
    • Several tips regarding Foswiki Macros
    • Personal Information Manager
    • Project Tracking and Reporting framework
    • Corporate web framework
    • Public collaboration site
    • Knowledge management
(does the names ring any bell? wink )

That way there is no "one-book-for-everyone" but "one book for each one".

-- RafaelAlvarez - 14 Jan 2010

It might be a good proof of concept to start a community driven book in a new web on foswiki.org

Start with the table of contents, and have multiple people take on sections.

Perhaps use ApprovalPlugin, or WorkflowPlugin, or another simple form for each page to designate revision status, authorship, etc.

Finally PublishPlugin to produce it when all topics are approved.

Send the PDF through lulu.com for the virtual to physical conversion, wikipedia notability established, Bob's yer uncle.

-- CraigBowers - 14 Jan 2010

I tried to find something I could link to, to help explain what a "Structured Foswiki" is. This was for a technical audience, familiar with databases, but not Foswiki and not the concept of structured wikis. I needed diagrams.

When we do have a place for the book, I'd like to help work on more diagrams for Foswiki. Not claiming to be a brilliant document-or-diagram-atician but when there's somewhere to put it, will plonk my first attempt there for a start.

Go book smile

We urgently need a better commenting solution. I'm thinking of a plugin that wouldn't render any comment related guff in the initial page GET, just a placeholder DIV. Then some AJAX that hits a rest handler to retrieve relevant comments for that topic, and build up the reply/UI dynamically. Much like the way disquss works. That way it wouldn't affect page view performance, and you could even utilise a totally different foswiki instance to run the comment service.

-- PaulHarvey - 15 Jan 2010

Just to remind as a possible source of inspiration for a communitiy driven Foswiki book, a book about TWiki has been published in German just before the fork (on www.amazon.de).

-- IngoKappler - 15 Jan 2010

Here are a couple of thoughts. Like Craig mentioned, it would be cool to write the book in a new web. I loved Eric Meyer's book on CSS which had a chapter on "how would one write this book using solely HTML+CSS". It was a very useful chapter and gave me many ideas on how to create great looking documentation using a structured wiki plus explicit macro/css support.

If the book was written as a wiki, it would serve to highlight a number of different things:
  • show how documentation can be created collaboratively (that's the whole idea, isn't it?)
  • show how documentation can be structured and presented for different audiences; instead of a different book for each user (as suggested above), how about a different reading flow for each target user ... managed by unique table of contents, section includes, etc.).
  • show how documentation can be made to look beautiful, potentially with a different skin and maybe a new set of macros that support book writing
-- PankajPant - 15 Jan 2010

Isn't this book idea more or less related to the long awaited and often proposed 'applications' web? I suggest to use a fresh subdomain http://book.foswiki.org for this 'project' and propose to ask people with publishing know-how like e.g. WolfMarbach if they he's interested in getting a second edition of his 'TWiki' book, but based on foswiki applications. I bought and read wink the following Wiki related books already and they all suck when it comes to how do I actually apply this cool technology to my real lifes daily problems:
  • 2001
    • The Wiki Way: Quick Collaboration on the Web / Bo Leuf, Ward Cunningham
  • 2005
    • WikiTools / Anja Ebersbach, Markus Glaser, Richard Heigl
  • 2006
    • Wikinomics: How mass collaboration changes everything / Don Tapscott, Anthony D. Williams
    • The starfish and the spider: The unstoppable power of leaderless organizations / Ori Brafman, Rod A. Beckstrom
  • 2007
    • Wikis for Dummies / Dan Woods, Peter Thoeny
  • 2008
    • TWiki: Installieren, Konfigurieren, Administrieren / Wolf Marbach
    • Wikipatterns / Stewart Mader
The best (IMHO) of the above list regarding usage aspects is also the thinnest, namely Wikipatterns, which uses 'Case Studies' to support the provided concepts. Its content is also mainly based on a community driven webpage of the same name.

Anyway, the content of the book should be done/doable by any Foswiki user, while any potential money made with it shall/must get to the Foswiki developers, officially represented by the association.

I fully support any activity that shows how Foswiki can be used to build useful content.

-- FranzJosefGigler - 16 Jan 2010

I fully agree. It would be a wonderful thing to have a Foswiki book/manual. But do not underestimate the effort to write a book. It took me more than 300 hours to write that TWiki took, which intention was to enable users to really understand the way it works by explaining the commands using simple examples. To write the samec for Foswiki and adding a guideline for applications (either writing them or using existing ones) would take at least around 600 hours.

When I think how many I have sold (in German though) and what I have earned respectively I would have been better of filling shelves at the supermarket.Thus unless somebody is paying for (or sponsoring) such a book nothing will happen. Hence the community should be clear about the fact that they cannot have any word in such a project (just advising through one to three representing members). Otherwise it would not ever been accomplished.

Just my 2 cents.

-- WolfMarbach - 15 Mar 2010

I personally like the style of Beautiful Code - Leading Programmers Explain How They Think: independent chapters written by different authors, requiring "less" coordination between them. That's why the FoswikiAtWork idea seems so much more viable.Of course, in this case the chapter will a have a strong element in common, in this case Foswiki use cases.

-- AntonioTerceiro - 16 Mar 2010
Topic revision: r14 - 16 Mar 2010, AntonioTerceiro
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy