[coyotos-dev] Documentation: CMS or SCM?

[David Hopwood]

Jonathan S. Shapiro wrote:
> On Sun, 2007-09-02 at 02:44 +0100, David Hopwood wrote:
>> 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/>
> 
> First, Trac is not an SCM.

I didn't say it was. For the CMS to provide its own SCM would be
redundant; all you need is for it to interface (perhaps "integrate" was
the wrong word) with the SCM that is being used for the Coyotos source,
Mercurial.

(It seems, based on <http://trac.edgewall.org/wiki/VcRefactoring>,
that improvements to Trac's Mercurial support are considered a high
priority.)

The main difference between a wiki-with-page-history, and a wiki that
stores its content in an SCM, is that in the former the page histories
are independent: there is not any notion of a version of the whole wiki,
only versions of pages. OTOH, I think it would be possible to simulate
whole-wiki versions (or versions of specific multi-page documents) by
using the tags plugin for Trac.

> It is a wiki integrated with a bug tracker.

And a source/changeset browser, and a template engine
(http://genshi.edgewall.org/).

[...]
> Second, Trac is what we initially tried, and we concluded that it is
> hopelessly inadequate for our needs. The bug tracking model does not
> incorporate the notion of a product with multiple components.

The current version definitely does support that. Example query:

<http://trac.edgewall.org/query?status=new&status=assigned&status=reopened&group=component&milestone=0.11&order=priority>

Note that you can also add custom bug fields:
<http://trac.edgewall.org/wiki/TracTicketsCustomFields>

and there is some support for bug dependencies:
<http://www.trac-hacks.org/wiki/MasterTicketsPlugin>

In fact it seems as though Trac has come on quite a bit recently, and
should be reevaluated. Its bug tracker is not as feature-complete as a
dedicated bug tracker like BugZilla (search is not as comprehensive,
for example), but I couldn't see any showstopping omissions -- even
after going through the BugZilla feature lists looking for some.

(One potential irritation is the inability to remove spam from bug comments:
<http://trac.edgewall.org/ticket/454>. I'm sure that will get fixed.)

> The wiki is fast and simple, but probably too simple for our needs.

Fast and simple is good. Besides, it seems to be fairly feature-complete
to me (although many features that are built-in to other wikis are
implemented by plugins). The only features in the wikimatrix.org list
that it does not implement, are:

 - minor changes (intentionally not supported, but see
   <http://trac.edgewall.org/ticket/38#comment:10>)
 - math formula support
 - orphaned page detection
 - themes (this is being worked on, see
   <http://trac.edgewall.org/wiki/TracDev/Proposals/ThemePlugins>)
 - XML export

I don't think any of these are critical.

Comparison with WikiMedia:
<http://www.wikimatrix.org/compare/TracWiki+MediaWiki>
<http://www.wikimatrix.org/forum/viewtopic.php?pid=1334>

>> 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.)
> 
> All of these are things that I have looked at in the past at various
> times. In spite of their flaws, I think we will stick with Drupal for
> now -- we need to move forward, and the whole "choose a wiki" issue took
> far too much time.

I clicked around both the Trac issue tracker for Trac, and the Drupal
issue tracker for Drupal. It is quite noticeable how much better cross-
referenced the Trac bugs were. Drupal requires users to paste the full
URL for any link, and the URL itself gives no indication of what it
is (e.g. <http://drupal.org/node/37371>). In Trac, there are shortcuts
for various kinds of link, e.g. "#123" links to bug 123 without any extra
markup.

Also on Trac, it's possible to transclude bug queries and summaries of
recent changesets for particular modules, which was used to very good
effect (especially on trac-hacks.org). On Drupal there were links to
equivalent queries, but they not nearly as effective as transclusion:
you had no idea whether following one of these links was going to be
remotely useful.

I was not able to edit anything on the Drupal site (after registering).
Maybe this is just a permissions issue, but the site didn't feel like an
open wiki at all, which the Trac site did (and I ended up making edits
to several bugs there).

Of course this is a matter of user culture and site policy as much as
technology, but the overall effect was that the Trac site was much easier
to navigate, and seemed more collaborative.

>> Storing lots of content in a wiki markup language does bother me a
>> little because there are no standards,

I was not until just now aware of WikiCreole (http://www.wikicreole.org/),
which TracWiki has a patch to support:
<http://trac.edgewall.org/ticket/4356>.

>> and every such language is slightly different.
> 
> I agree, though translating in and out is not that difficult. One
> positive point about Drupal is that its preferred markup language is
> [X]HTML.

I don't think this is a big issue. There is nothing especially wonderful
about either HTML or XHTML.

(A few years ago I decided to use HTML instead of a wordprocessing format
for some of the documents associated with my business, on the grounds that
this would avoid locking them to a particular wordprocessor. I wish I
hadn't bothered -- they actually ended up being more presentation-oriented
and fragile in HTML.)

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