« Previous day (May 22, 2005) | Main | Next day (May 24, 2005) »

Mavenbook.org for the Maven Book

posted 09:54PM May 23, 2005 with tags by Lars Trieloff

Vincent Massol is currently writing the Maven Book. And he has set up a website for this book containing News and Tips for Maven users.

CompareML for Comparisons

posted 09:36PM May 23, 2005 with tags by Lars Trieloff

If you would like to write comparisions like this comparison of SCM systems, you might want to take a look at CompareML, an XML language for comparisons.

CompareML can be converted to DocBook or HTML.

Wiki, DocBook, Documentation

posted 09:14PM May 23, 2005 with tags by Lars Trieloff

There are severla people who perfer Wiki-Style markup and the Wiki-way to DocBook for writing technical documentation. When the need for documentation arises, they will set up a wiki and let the users create documentation by themselfes. When they note that there is a need for high-quality documentation, they will not take the hard, but correct way to edit the contents of the Wiki and rewrite it into a proper DocBook document, but they will seek a DocBook export filter.

This leads to inferior results, mainly because Wikis are designed for notekeeping and simple markup with litte semantic information, while DocBook is highly structured and all about semantics.

Sean Coates, writes for the PHP documentation project: Wikis are not for documentation.

In (2), Wikis are known (and consequentially popular) for their simplicity. Anyone who's tried to create a *||Multi|Column|Table||* would agree that they're meant for simple markup only (but often have certain "complicated" functionality). Sure, it would be possible to implement wiki-specific markup for things like and &entities; but for each one, additional wiki syntax would need to be added. Once enough new syntax was added to accomplish similar goals (robust wiki->docbook conversion), you'd have a toolbox that's no simpler than docbook. Wikis are unstructured, by nature.

Tools like the DocBook Wiki do not solve this problem either: they bring DocBook markup to the Wiki-world, but it is too complicated for this kind of applications and unattractive for Wiki users.

Wikis are useful for developing and drafting documentation, but they do not replace a structured and managed documentation creation process.

« Previous day (May 22, 2005) | Main | Next day (May 24, 2005) »