>Cramps on Single Sourcing with Wikis

>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:

  • bold
  • italics
  • underline
  • image
  • code

And for capturing the very basic structure of a document:

  • paragraph
  • line break
  • sections

However going beyond this they really struggle with representation. You can create your own tags for capturing more structured information like:

  • important
  • tip
  • note
  • examples
  • code listing
  • screen shots
  • figures
  • citations
  • bibliography entry
  • glossary term
  • steps/procedures

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.

Advertisements
This entry was posted in documentation, eclipse, wiki, xml. Bookmark the permalink.

7 Responses to >Cramps on Single Sourcing with Wikis

  1. Antoine says:

    >and Textile ? Markdown ? Tried those ?

  2. skleinei says:

    >Try Confluence + Scroll.Confluence has a range of various macros, which Scroll converts into DocBook.-Stefan(K15t Software)

  3. David Carver says:

    >@skleinei yes, you have to create additional macros but that gets back to my point. DocBook, DITA, Tex, and other single sourcing options already have the options built in.@Anotine: Nope haven't tried those, but from what I see of Textile, it's just another wiki like markup language targeted for style not structured content. It suffers the same flaws as other wiki markup, losing the semantics of the data that go with it. Markdown suffers the same thing. How can I represent a figure with a title, without creating a custom macro template that will be different on every wiki I visit?Wiki's are designed for quick publication not for tracking the structure of the document they represent.

  4. David Carver says:

    >Here's the ultimate difference. DITA, DocBook, Tex all are markups for the publishing industry… wiki is ment for display and quick collaboration on the web. So different views on what is important.

  5. >Yes, the fact that there is no standard wiki format makes me cry.I do think there is some happy medium between things like docbook and wikis. I think we are working towards that.

  6. David Carver says:

    >@Chris: Well, this is one WikiCreole. An effort to create a standard wiki syntax of the most common items. For eclipse, I think we can get to an 80/20 rule, where we have the most commonly used items created so we can go back and forth easier.

  7. >Wiki markups suffer from two mistakes: They were designed by people who believed that they can design languages (and belief is, as we all know, a very personal thing) and they fulfill only the first part of "simple things should be simple, complex things should be possible".

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s