About

Sarma is a live, over-the-web documentation editor supporting DocBook imports and exports, per-unit (paragraph, title, figure, ...) revision control and handling, and WYSIWYG interface to make editing docs a natural process: you view it and edit it right away. It's written by DaniloSegan as his Google SummerOfCode project.

Demo

Stop by Live Demo page to try it out in the current state!

Getting It

Sarma lives in Gnome CVS module "sarma". There are currently no tarballs.

Instalation

If you want to install it on your server, you will need the following software:

• Python 2.3 or newer

• libxml2 and libxslt along with their Python bindings

• Cheetah Templating engine for Python

• SQLObject 0.6.1 or newer

• Depending on the backend you wish to use with SQLObject, you'll need either Python bindings for MySQL, PostgreSQL or SQLite, and appropriate development libraries for those as well

Then all you need to do is to set up a path in docstorage.py to SQLObject connection path, and import a couple of documents in a database using import-db.py.

To use as a client, you need a Gecko based web browser with support for designMode (Midas): 1.3 or newer should do (and this includes Epiphany with which I tested most of the time, Firefox, Galeon, and other Gecko-based browsers).

Development (to be rewritten)

Basic ideas

Instead of going for Wiki-style editing, I'd rather explore using Gecko-based designMode (WYSIWYG editing), with very granular locking (like per-smallest possible unit, i.e. per-paragraph, instead of per-section or per-sourcefile) and good translation support. Using all the modern features of a browser (like ECMAScript, DOM, XMLHttpRequest, or translated to buzzwords "AJAX") for client-side, to good integration with existing tools on the server-side (like generating minimal [i.e. ignore whitespace changes if desired] unified diffs for changes between document revisions).

Outline of steps to take

1. Define and recognize the needs of Gnome documentation: full DocBook is overkill, though it should be editable (look at what ShaunMcCance has already done with Yelp and gnome-doc-utils stylesheets: Yelp already caters for most of the things Gnome documentation really needs)

2. Develop infrastructure to support authentication and user privilege management, to be used by documentation project leaders and regular users
3. Make backends for working with documentation (separating content from structure, in-place editing, etc.: my experience with xml2po should help here a lot)
4. Connect designMode with backends, create usable UI (this would take most of the time)
5. Allow establishing direct relations with documents managed in CVS/SVN/arch/whatever other VC systems, including "tagging" official documentation in live-editing repository
6. Optionally, consider creating a couple of web-services to allow for off-line tool development (like integrating Conglomerate with it)
7. Deliver!

Technicalities

My language of choice would be Python, which I have a fair share of experience with, and which is very much suitable for the task at hand (simple to read and write, popular [so others can contribute], bunch of useful standard modules, etc).

Resources

• Gecko DOM Reference

• Links and resources from Mozilla.org

• JavaScript Scripting

• XML in Mozilla

• XML Extras (XmlHttpRequest)

• Rich Text Editing, aka designMode, also here

Comments?

PaoloBorelli: <disclaimer>I'm pretty clueless about docs and it's late night here, but since Danilo didn't tell me to shut up on irc, I'll give my rant here</disclaimer>

I was imagining a sort of "circular" system here:

Static Content (web, yelp) <---------- Persistent storage (cvs, subversion, whatever)
        |                                                 ^
        |                                                 |
        V                                                 |
Distributed editing (wiki, WYSIWYG client)------------> Editor's Review (specific tools)

1. Static Content is what Joe User would see using yelp, browsing online documentation, etc. This documentation would be guaranteed to be of good quality (e.g. revised in order to make sure that it doesn't contain misleading information). It would be automatically generated from the repository (cvs, subversion, whatever).
2. From the contents it should be possible to quickly and easily access a "feedback" mode where a willing user can edit the documentation and submit improvements. The user should also be able to ask for clarfications on a part of the document (maybe going to bugzilla?). This editing should be easily accessible (low learning curve required) and distributed (people should see latest changes made to the document)
3. A team of people (the Editors) should be able to take a "snapshot" of the ditributed editing, review it and eventually check it in the revesion control system. This is the step were many good tools would be needed: these tools would take care of taking a snapshot of the contents and provide the editors with support for their review. This includes things like showing an history of the changes made to the documents, let the editor cherry pick from the various versions, let the editor quickly edit the document, spell checking support and many more. It should also take care of converting the text to a format like docbook that is more suited to store in cvs and then transformed to generate the static content.
4. The edited document would be checked in the version control system, registering the history of the changes. Note that such an history would not be cluttered with wrong docs, spam, etc.

Let me note that step 3 (the Editors) doesn't necessarily mean a small group of doc experts, but could be distributed pretty well, in a way similar to the bugsquad. For instance a lot of trusted people could just take care of spam, completely wrong docs, typos etc. Docs Maintainers (the small group really intimate with how docs work) still would have the chance to give a generic review before the documents go live from the repository to the online content, e.g. before a release.

Monodoc

I think a great place to start looking for a collaborative and automaticaly updating documentation is mono's system. The monodoc browser allows the user to edit and submit pages (something that does require account registration, and a small degree of accountability). And changes are shown at their doc site -- KevinKubasik

Dokodo

Dokodo is an attempt worth testing, no code yet but a screencast. Read also the description by Mike Orr (It's a long text; find 'Dokodo' with FF.). Apparently, is uses TinyMCE for editing. -- ClausSchwarm

UI

More work is needed both on "sarma" UI and it's integration... We can learn about UI and organization from Distributed proofreaders project and Project Gutenberg. -- GoranRakic

GPLv3 Draft tool

The GPLv3 draft website has a tool to comment specific parts of the text (http://gplv3.fsf.org/comments/gplv3-draft-2.html). Something great about the tool is that the most commented sections have darker backgrounds, and you can view the comments relevant to each part.

This looks like something very useful for maintainers, who can easily spot the more confusing parts of the docs and allow users contribution without leaving them out of context and without the problems of non edited content. Maybe this idea can be brought to Sarma. One possibility could be having the highlighted version as a maintainer's view, and keep comments as in a forum, if the highlighted version looks too confusing. --Pachi

JavierJardon: related wiki page: DocumentationProject/GtkDocFuture