Thread

Hi, I’m writing a quite large documentation, and I’m getting a bit annoyed at writing HTML for everything.

So what I wonder is: Do you know a good language for writing documentation?
Benefits? Drawbacks?

I have heard good things about docbook. But it seemed overly complex to me so never really learned how to use it. I also read phpdocumentor can create documentation in docbook format but again haven’t used it.

wikimedia might work good for this

I like dokuwiki:

DokuWiki is a standards compliant, simple to use Wiki, mainly aimed at creating documentation of any kind. It is targeted at developer teams, workgroups and small companies. It has a simple but powerful syntax which makes sure the datafiles remain readable outside the Wiki and eases the creation of structured texts

markdown I suppose.
pros : lots of places use it.
cons : the syntax sucks

Of course you could also use a knowledge base system for writing the documentation. 😊 http://68kb.com

I would like something with good syntax (which, as you stated, Markdown is lacking).
I also like to be able to generate static HTML pages, to be able to easily distribute an offline version of the manual.

You know this is something I am also wanting to do but I want to keep my html files in svn. 

However I had some time tonight to run a test and came up with this:
http://68kb.com/124894/how-do-i-create-a-php-info-page.html

All of those are static html files generated from articles inserted using 68kb.  I also tried to keep it close to the CI project documentation but keeping some sort of easy to use navigation.

At any rate if you love it or hate it let me know. I thought something like this opens up a lot of possibilities.

Why not use yaml and then simply process it?