User:Patri/SeasteadBookCollaboration

The next edition of the seastead book will be produced collaboratively, by at least Patri & Will, possibly additional authors. This requires a software environment that supports us. Several people have offered to help with development, and several solutions have been proposed.

Requirements

• Collaboration. Easy for each author to work on the book, and combine the changes. No emailing Word files back and forth. Doesn't get in the way of writing.
• Version tracking. Can see previous versions and revert to them.
• Flexible structure. Must be easy to modify the hierarchy by adding new sections (at any level) and rearranging/promoting/demoting existing sections.
• Markup which is good for publishing / typesetting, but doesn't get in the way of writing.
• Can export to HTML and PDF (for printing).

Things that would be nice to have:

• Easy reviewer commenting on drafts.
• Offline access.
• Solution exists, minimal extra coding.
• Edit in text editor of choice, ideally one that understand the markup language

Solutions

Markup Language

This will partly be driven by the environment, but...

• TeX or something that can be turned into TeX seems ideal. If Donald Knuth has solved a problem, we should probably use that solution.
• HTML is another option. The book is currently in HTML. It makes publishing to the web easier, but print harder, and print is our main goal for this edition. HTML can be translated to LaTeX (the beta version of the book is Markdown -> HTML -> LaTeX -> PDF) but it is somewhat messy.
• DocBook is a common format, but don't have any particular reason to use it.

Environment

Two main systems have been proposed:

Web based

The two examples are using a wiki and using Thiblo. These options get you:

• Central repository and change tracking (since they are accessed through a website to a database)
• Ease of publishing HTML version (since you are essentially developing on live webpages)
• Ease of commenting, for co-authors, reviewers, etc. (Wiki includes discussion pages, Thiblo includes sentence-by-sentence commenting)
• No simultaneous editing of the same page.
• Flexible structure - we can control the structure through a master index page.
• Wiki can be customized to use Markdown. Not sure of Thiblo's markup language.
• A custom script could export LaTex or a PDF from a Wiki. Thiblo plans to add LaTex export as well.
• No offline access, AFAIK, so also no using a text editor. Have to use a browser, which adds one more layer of instability / abstraction / borders.
• Solution exists - Somewhat, requires some extra coding for our needs.

Version Control based

In this system, the book consists of a file for each section, located in a VCS such as svn or git. The files are written in a markup language like Markdown or TeX. Authors can edit independently, and sync / merge their changes. The book's order is controlled by a master index file listing the hierarchy of the files.

• Collaboration - yes, very easy, including simultaneous editing & later merging.
• Version tracking - yes.
• Flexible structure - yes. Can even do GUI by using OmniOutliner and XML export. Need a script to read it.
• Markup - whatever we want. Markdown, TeX, up to us.
• Export - Need to write scripts to do it, but can export to anything, incl. multiple targets
• Commenting - Nope, not unless we somehow export to Thiblo.
• Offline access - Yes, version control works great with offline access.
• Text editor - Yes, can use any text editor, and there are many that support Markdown and LaTeX.
• Solution exists - Somewhat (VCS exist, markup languages exist), but will require some extra coding for our needs.

Developers

Several people offered to help on Patri's LJ posts: [1] and [2]:

• jon_leonard, especially if it is LaTeX based.
• proctologiste
• nots2good
• sanityjihad
• hodja - thiblo developer
• baldvin - thiblo developer