Collaborative Publishing Based on Community Feedback

By Keith Fahlgren
May 21, 2009 | Comments: 10

Over the last few years, traditional publishing has been moving closer to the web and learning a lot of lessons from blogs and wikis, in particular. Today we're happy to announce another small step in that direction: our first manuscript (Programming Scala) is now available for public reading and feedback as part of our Open Feedback Publishing System. The idea is simple: improve in-progress books by engaging the community in a collaborative dialog with the authors out in the open. To do this, we followed the model of the Django Book, Real World Haskell, and Mercurial: The Definitive Guide (among others) and built a system to regularly publish the whole manuscript online as HTML with a comment box under every paragraph, sidebar, figure, and table.

After the impressive success of the Rough Cuts program from Safari Books Online, which we've long supported, and Real World Haskell, which used a similar system, we we're extremely eager to try the idea out with more titles. Here's how Bryan O'Sullivan, one of the authors, summarized the idea once they were close to submitting their manuscript for publication:

How has our system of open, incremental development worked out? In my estimation, it has been a fantastic success, far overwhelming my expectations.

  • We have received 7153 comments so far.
  • That's an average of 1.73 comments per paragraph.
  • The usual number of technical reviewers for a technical book is 2.
  • 748 people have commented so far on our drafts.

Feedback from our readers has had a profound effect on the development of the book. We have received comments from people who have been using Haskell for almost 20 years, from casual hackers, and from people who are just picking up the language for the first time. We have used your input to make our coverage both more correct and more accessible. Thank you all for the generosity you have shown with your time and attention!

Bryan has since open sourced his Django-based feedback system as part of the development of Mercurial: The Definitive Guide. [Full disclosure: I'd pushed Bryan to open source the system as Real World Haskell was in development, but he was awfully busy at that time for some reason. I discovered that he'd done it for Mercurial instead just two days before our first OFPS alpha was ready.]

The book in question is Programming Scala, by Dean Wampler and Alex Payne. We're very grateful to them for volunteering for this project. Readers are particularly hungry for good resources on Scala itself, because the publishers are just starting to publish books about it. That relative dearth of titles combined with its unique combination of the allure of functional programming, the familiarity and power of object-oriented programming, and the stability of the JVM should make it another great test case for showing the power of involving the readers in the development of the book.

Many thanks to Liza Daly, who wrote the underlying system for us.


Great work -- both from the content side to the execution of the UI. One small request, though -- I found the placement of the "comments" link at the bottom of each p-graph distracting. Have you considered placing them to the side?

You're reinventing a user interface that's over 500 years old, so pick your battles where you can, but a "comments in the margins" is a better reading model (for me, at least) than something that interrupts the flow.

I completely agree, Andrew. I actually raised this with Keith a few weeks back when he showed me a prototype. That version had the comment links (and comments) on the left side, which I found to be far too disruptive to normal reading. I think comments on the right is an improvement, but comments in the margin would seem to be a clear winner over either form of in-line comments.

What is the Django based feedback system called and where would one get it? Is it Mercurial - the version control software? I'm a little confused about that part.

Is OFPS itself open? Can I download it, run it on my own server, modify it, etc? If so when can I get it and where?

This is all very cool stuff.

@JR: I don't think Bryan has named his Django-based system. He's using it to power the feedback system for Mercurial: The Definitive Guide. The Mercurial repository for the book's content includes the source code for the system, specifically the web/ directory.

OFPS isn't open source today, although we're discussing that internally. Liza, the developer, blogged about some of the architectural details.

Thanks so much Keith. has been doing this for the past 1/2 year.

I have the offer to make your books more interactive. I have patents for this decision. Your publishing house can be interested?

Hi there,
We recently launched an open source tool that does exactly the same than OFPS. It's called "Wooki", and its released under Apache 2 license and available on Github.

It's made with Tapestry 5 framework for Java, and jQuery. It's still a young project, but we working hard on it. We already have cool features like "on the fly" PDF generation.

- The wooki team

It's made with Tapestry 5 framework for Java, and jQuery. It's still a young project, but we working hard on it. We already have cool features like "on the fly" PDF generation.

We already have cool features like "on the fly" PDF generation.



The free platform for reading EPUB books online from any device.

Integrated with O'Reilly Labs 02/09/09.

First translations added 03/11/09.

Feedbooks integration & one-click addition added 07/29/09.

Beta Projects

Open Feedback Publishing System (OFPS)

Participate in collaborative community feedback to help refine in-progress, open manuscripts like Building iPhone Apps with HTML, CSS, and JavaScript or the published Programming Scala.

Released 05/20/09.

O'Reilly Product Metadata Interface (OPMI)

Want to know all we know about an  O'Reilly book? Give us an ISBN and we'll let you in on our (RDF) secrets!

Released 02/09/09.

Open Source

DocBook-XSL 1.74.3 with Improved ePub Output

Keith Fahlgren (O'Reilly Media) helped release the stable 1.74.3 release of the open source DocBook-XSL project and improved the EPUB generation stylesheets. Paul Norton (Adobe) and Liza Daly (Threepress) provided very helpful patches.

Released 02/17/09.

DocBook-XSL 1.74.0 EPUB Output

Paul Norton (Adobe) and Keith Fahlgren (O'Reilly Media) have contributed code to the 1.74.0 release of the open source DocBook-XSL project that generates EPUB documents from DocBook. An alpha-quality reference implementation in Ruby was also been provided.

EPUB is an open standard of  the The International Digital Publishing Forum (IDPF) and something O'Reilly is trying  to help gain wider adoption.

Released 06/02/08.