[coyotos-dev] Documentation: CMS or SCM?

[David Hopwood]

Jonathan S. Shapiro wrote:
> We have an open issue: should we manage documentation primarily in a
> content management system (CMS) such as Drupal, or should we manage
> documentation primarily in a source code management (SCM) system such as
> Mercurial?
> 
> I'm torn. The CMS route has the advantage that it lets people work with
> us to improve the documents actively and immediately. If something is
> busted, you can just go in and edit it. At the very least you can
> comment on it. Unfortunately it does not give us any sort of a document
> version control mechanism.
> 
> The SCM route gives us versioning without interactivity. It's not really
> possible for people to comment directly if we go that route.

It sounds like what you want is a CMS integrated with an SCM. The most
comprehensive open-source example of that I'm aware of (I assume we want
open source?) is Trac: <http://trac.edgewall.org/>

I haven't used it myself, but from clicking around the web site, it
seems to do everything you might expect. It perhaps isn't as feature
complete as something like Drupal when considered as a CMS, but it is
arguably more complete when considered as a collaborative software
development platform, which I think is what we actually want.

Alternatively, there is standalone wiki software that uses an SCM for
page storage. (When I asked the wizard at www.wikimatrix.org about this,
it suggested JSPWiki, KeheiWiki, MoniWiki, PhpWiki and TWiki.) Even
those that don't, often support page history and diffs -- if we wanted
to go down that route I would suggest MediaWiki. However, I think Trac
is probably a better fit to our requirements, so let's look at that
in more detail:

Trac works like MediaWiki in that it stores page history in a database
(SQLite by default, PostgreSQL and MySQL also supported), not in the SCM.
There is a proposal to allow storing page history in the SCM, described
at <http://trac.edgewall.org/wiki/TighterSubversionIntegration>. That
would be nice, but in any case, the important point is that page history
and diffs are supported -- exactly how is an implementation detail.
(Presumably if that proposal were implemented, there would be a way to
transfer existing database content and history into the SCM.)

Trac supports Mercurial via a plug-in, although this is decribed as
experimental in <http://trac.edgewall.org/wiki/TracMercurial>.
(See also "Bugs and limitations" near the end of that page.)

Storing lots of content in a wiki markup language does bother me a
little because there are no standards, and every such language is
slightly different. But Trac uses a wiki markup that seems mostly
compatible with MediaWiki, so I don't think we would be locking up
our content into too obscure a format.

There is some support for CAPTCHAs and spam filtering
(<http://trac.edgewall.org/wiki/SpamFilter>,
<http://trac.edgewall.org/ticket/4034>).

There is support for syntax highlighting, which looks like it would be
flexible enough to accurately handle BitC and E (for the time being,
the highlighting for Lisp/Scheme and Java will do).

Scripting is in Python, rather than some more objectionable language.

You mentioned the requirement to generate printed docs. There is a
Trac-to-PDF converter at <http://trac-hacks.org/wiki/CombineWikiPlugin>.
I don't know how good the output is, but it seems to be under active
development, judging by
<http://trac-hacks.org/report/9?COMPONENT=CombineWikiPlugin>.

-- 
David Hopwood <david.hopwood at industrial-designers.co.uk>