>I’ve been working on the eclipse Documentation Guidelines for Single Sourcing using the eclipse wiki. One of the things I’m discovering is that wikis are great at capturing unstructured information and styling:
And for capturing the very basic structure of a document:
- line break
However going beyond this they really struggle with representation. You can create your own tags for capturing more structured information like:
- code listing
- screen shots
- bibliography entry
- glossary term
But once you start doing this, isn’t it almost better just to go and use something like DocBook or DITA that was designed from the begining to capture this information. Wiki markups are first and foremost a way to allow easy collaboration for Web Based communication. While you can get them into a variety of formats, you loose a lot of meaning of the structure and semantics of the data that is being represented. Wikis are popular in some aspects as most people don’t care, they just want to write the content.
However, if you want the control of how that information looks and to be able to represent it differently on different platforms, one eventually needs to separate the presentation aspect of wikis from the content they are capturing.
Personally, I still think DocBook does this the best, and the most straight forward. From what I’ve seen, many wiki dialects are getting just as wordy as the XML that people say they don’t like.
Note: If you want to have the best of both worlds, consider DocBookWiki.