Vincent Massol Think Tank - Project Documentation: Wiki -> CVS -> ML -> HTML

Project Documentation: Wiki -> CVS -> ML -> HTML

[ vmassol ] 11:05, Saturday, 17 May 2003

Having project documentation written in XML (xdocs) and stored in the project's CVS is great as it allows changing the style without chasnging the content. It also allows to easily write directly the docs in XML format

That said, lots of persons do find that writing xdocs is a pain. Moreover wouldn't it be nice if end users could easily contribute to the documentation?

Here's a solution:

Use a Wiki for the project's web site. But not any wiki. Use a wiki that stores it's web pages in XML format, such as MoinMoin (Here's an example of generated XML. Use View Source for IE users).
Then write a hook (script) in that wiki so that the modifications get saved to your project's CVS (or even better use CVS as the underlying storage for the Wiki). Question: is that directly supported by MoinMoin?
(optional). Use a CVS syncmail script to send CVS commit diffs to the project's development mailing list. This allows everyone subscribed to see the changes to the documentation (and to the sources of course).
(optional). Now that we have our XML doc sources saved in the project's CVS we can (if we wish) generate the docs in an HTML format different than the wiki we are using, for packaging them in the project's distirbution for example.

Nice, no?

Projects as Forrest (Jakarta) (dedicated to project documentation, indeed !!) inspired me other ideas..

Why not writing directly docs in wiki format in CVS ? I've seen attempts using Chaperon (raw-text to XML transformer) to generate XML from wiki format files...

Advantage: it's easier to write wiki format than xml format, in my opinion. Any text editor can still permit to edit the doc.

Last thing to find: a renderer integrated to the editor or associated to .wiki files themselves to "preview" .wiki files.

Second thought: in fact, i remark that i just would like to be able to write docs very quickly. So yes in an open format BUT also using a powerfull wysiwyg editor. So i thought: and if MS Word was an XML editor ? Well, i shouldn't be difficul to do a bijection between Word "styles" and Anakia tags..

--Dominique, May 17, 2003 02:28 PM

> Why not writing directly docs in wiki format
> in CVS ? I've seen attempts using Chaperon
> (raw-text to XML transformer) to generate XML
> from wiki format files...

Yes. This is exactly what I have in mind and what I described. The MoinMoin wiki is doing this (generating XML files). What I don't know yet is whether it supports CVS as a built-in feature for storing the XML pages.

> Last thing to find: a renderer integrated to
> the editor or associated to .wiki files
> themselves to "preview" .wiki files.

Yes, the MoinMoin wiki supports a preview mode too.

> So i thought: and if MS Word was an XML
> editor ?

Yep. But :
1/ we need to wait for Office 2003 to be able to save docs as XML
2/ we still need to perform an XML transformation from the word format to the wanted format (xdocs or docbook for ex). The MoinMoin wiki generates xdocs (Stylebook format)
3/ The wiki automatically publishes the docs. If we use word we would also need some publishing infrastructure such as a webdav server. Maybe subversion when it supports the LOCK feature?

--Vincent Massol, May 17, 2003 02:56 PM

Office isn't really going to support XML or at least not in a useful way. Open Office currently uses XML as it's native format. I was looking at this to allow people to use OO to edit XML content but the DOM used within OO is not really suitable as it's more of a markup stream than a structured document.

Because of this I've started to get involved in this project http://www.conglomerate.org/ which is an XML editor designed to work with structured documents e.g. Docbook.

What would be very cool would be to hook this up to subversion. Conglomerate is built on the Gnome framework so should eventually support webdav via the gnome-vfs. You can then use the python hooks into the subversion server to present the docs to the user.

None of this is ready for public consumption but it's something to look forward to. Doesn't help anyone using windows though ;)

--Jeff, May 17, 2003 09:34 PM

Zynot is working on a similar thing to make their documentation for their distribution work. You can check it out at http://wiki.zynot.org/zynot/moin.cgi/ZynotDocs. We'll be doing things a little differently, but the idea is very similar. I'm looking for a way to convert DocBook into MoinMoin wiki, hence I found this article.

--flickerfly, July 8, 2003 03:13 PM