While not everybody agrees, it really feels like the Midgard Wiki way of generating documentation is working. The idea was to make the documentation more consistent, and to lower the barrier of submitting new content.

The feedback we’ve got about using Markdown as the wiki authoring format with some extended linking syntax has been very positive. Besides the main wiki, Aegir 2 development notes are now also using the same model.

Examples of completely new documentation areas submitted thanks to the wiki include:

• Midgard Query Builder API
• Midgard superglobals for PHP
• MgdSchema API for PHP

I was initially very skeptical about wikis, but Wikipedia really opened my eyes to the opportunities of the model. It is far more important to have easily updated and cross-linked documentation available than to fret about semantics or different publishing formats.

Before wikis we went the route of DocBook SGML - DocBook XML - XHTML, and none of the formats really met our requirements. DocBook produced very controlled documentation, but since contributing content for it was difficult most developers simply didn’t document their changes.

For Midgard documentation the wiki format also makes sense because we can use our own wiki software for it. Jarkko seems to agree:

jval: the wiki is nice - it supports normal midgard owner permissions, right? - if yes, it is possible to use n.n.wiki even for “normal” site content - think how easy it is to edit compared to ais :)