DokuWiki and Syntax

I have tried Dokuwiki for a personal wiki. It’s ugly. It forces me to edit pages as a plain text files, using it’s own wiki syntax format. It also stores articles in a format of wiki text. Every time somebody wants to view a page, Dokuwiki parses wiki-formatted file and produces HTML. Every time. That’s how article looks in a wiki format.

====== HiPath 4000 Backup destinations: ======
  - MO/CF
  - Server
    - NFS
    - FTP

====== HiPath 4000 HDD Layout ======

^Name	^Purpose	^Contents^
|:PDS:	|program disk	|RMX|
|:DBD:	|Debug disk	||
|:AMD:	|Administration and maintenance disk	||
|:CGD:	|Call change disk	|tarification files|
|:TMD:	|Traffic metering disk	||
|:PAS: 	|Miscellaneous usage	|REGEN file|

Looks ugly. That is a how your data is seen by both editor and application. Both editor and dokuwiki have to be able to understand wiki syntax in order to see the formatted data. Both are negatively affected. Editor has to learn a new syntax for writing an article, Dokuwiki has to translate article to HTML every time user requests it (many times).

The third victim is data itself. It gets transformed to an ugly format, compatible with the only software which is wiki engine you use. In other words, if you let a wiki engine take care about your information, the information would most likely stay in there forever. If you want to extract a document from a wiki engine, you have to render a page, using the engine.

Why do we need to have wiki-formatted intermediate presentation? The official answer is to help users who lacks HTML+CSS knowledge to develop a document structure. It probably worked in 2000, when there was no technology for creating interactive applications in a browser. Nowadays things changed. We have Google docs, which allows a document to be edited in WYSIWYG mode, and, moreover, to be stored and exported in any format. Some might say WYSIWYG editors corrupt formatting when used in a wrong way. It applies to documents where we need a style. In a Wiki we do not aim to create a document with style. We do aim to develop a document with structure. Style has to be generated by a wiki engine.

Hence, the best approach for wiki architecture is: editing documents in WYSIWYG, storing documents in a structured format without styles, presenting them as-is.

It is very important not to let WYSIWYG editor to define styles. It’s a common user mistake to apply styles to an articles. Styles has to applied by an application. An editor should define the structure of the document only: Headings, paragraphs, tables, code, bold, italic, etc. Editor needs no colours, no browser compatibility nothing extra.

Let the approaches be compared:

Stage Wiki-approach Correct approach Best approach
Editing Using ugly wiki format, which is neither a
document, nor a pure data
Using WYSIWYG editor, which allows editing
structure, but not styles.
Using WYSIWYG editor, which allows editing
structure, but not styles.
Storing Using ugly wiki format, which is neither a
document, nor a pure data
Using a structured document format, like (X)HTML,
XML, OD>
(X)HTML with no styles
Presenting Parsing wiki format, restructuring it to a
document (HTML+CSS)
Presenting a stored document as is+ applying some
predefined styles to it.
(X)HTML + CSS style
Engines MediaWiki, DocuWiki, pmWiki Almost there: WordPress, MoinMoin, Sharepoint wiki module… ???

Currently there is no Wiki engine in the market who does the job right.

  • As I am a big fan of DocuWiki, let me state few things here with regards to you points listed above:

    First of all, it is not DocuWiki’s syntax that is used there. It is a common wiki syntax, which you will find in most of other wiki engines as well. For example take wikipedia’s syntax page: http://en.wikipedia.org/wiki/Help:Wiki_markup
    You will find a lot of similarities there (though few things are different from one engine to another).

    More over, there are numerous plugins available at DocuWiki plugin page to help you with editing through WYSIWYG editors (even FCKeditor is there).

    DocuWiki does not render a page each time you access it, but uses cache where pages get re-rendered only after revision change. In addition there more plugins available to tweak the cache behavior.

    The fact that DocuWiki stores pages as-is (in wiki format) is also an advantage, since HTML is not always a good thing. For example if one wish to render a page in other format (PDF, POD, XML, …). Wiki format is much easier to parse and convert to whatever you want than HTML. In addition it is much lighter. Most of the wiki engines do store articles in native wiki format and keep cached HTML per revision.

    I’ve been using Wiki a lot and still use them almost in every company or project I am involved in and it is a great tool to have. The advantage of wiki syntax also a great thing if you type fast and don’t want to click on all those buttons in the editor, as well as type bunch of HTML in textarea. It takes 1 hour to remember all the syntax and then use it fast.

    One advantage of DocuWiki over other Wiki engines is that it does not require database and stores all info in plain files. It is much handy for small sized wikis. You don’t need to manage DB and backup as well as any migration is much easier.

  • T1

    1 – there is no “common” wiki syntax – they all are different. If there are few thinks different, syntaxes are incompatible. You can not easily migrate your data from dokuwiki to, let’s say, MediaWiki.

    2 – nice point. I only regret WYSIWYG it’s not default there

    3 – thanks for pointing me there is a cache. nevertheless, If you want to get XHTML in the end, then store data in XHTML. No extra intermediate (wiki-formatted file) needed. Check out Occam’s razor paradigm.

    4 – HTML is always a good thing. There is a W3C standard for HTML format and HTML rendering. There are already parsers for HTML which can render it to any other format. Rendering wiki-formatted page to other format is as easy as writing your own parser for a certain wiki style (which is never standard and varies by engine version). Storing files in a wiki format is just evil to users.

    5 – now i see why you advocate wikis so much. You simply spent too much time in learning, adapting the imperfect tools. But I can admit wiki-syntax might be advantage for the ones who seeks improved speeds of data input. Bit strictly not for data storage. Nevertheless I consider wiki-style typing a geek redundant feature like zsh, brainfuck and dvorak layout. Why learn another syntax, if there is WYSIWIG with shortcuts and a graphical mode at the same time? WYSIWIG is open to everyone, easy to learn, easy to use daily.

    FYI, you can also quickly type in HTML. Check out ZEN-coding.

    In addition it is much lighter. Most of the wiki engines do store articles in native wiki format and keep cached HTML per revision.

    that is very wrong. you have to store both HTML and wiki files. It consumes twice more space. Wiki is not MUCH lighter, it’s twice lighter at most. I believe, you want to point out that in a long perspective with many editions storing files in a wiki format would bring a big difference. I doubt someone wants to sacrifice compatibility ans reliability to gain some extra disk space :)
    Wake up, no one cares about space consumption nowadays. Everybody aims to readability and standards compliance.