Comments on: The Perils of Writing Good Documentation http://blog.reverberate.org/2009/07/30/the-perils-of-writing-good-documentation/ parsing, performance, minimalism with C99 Wed, 05 May 2010 20:14:07 -0700 http://wordpress.org/?v=2.8.6 hourly 1 By: Shalabh http://blog.reverberate.org/2009/07/30/the-perils-of-writing-good-documentation/comment-page-1/#comment-1477 Shalabh Fri, 20 Nov 2009 00:56:59 +0000 http://blog.reverberate.org/?p=250#comment-1477 Hi Josh, I used docbook for a couple of cafepy articles and even though it tends to be fairly verbose because of the XML tags, I would use it again. It has some built in features (such as callouts: http://www.docbook.org/tdg/en/html/callout.html, multiple output formats from same source, etc.) which make it attractive. All the XML tags do slow you down so for shorter articles where I don't need all these features, I stick with Markdown or reST based stuff. It should be possible to convert from any format to any other so I'm not worried about being locked-in. Also look at Sphinx (http://sphinx.pocoo.org/index.html) - it is reST based and was written for the Python language documentation. Looks like it can even do multiple output formats. Hi Josh,

I used docbook for a couple of cafepy articles and even though it tends to be fairly verbose because of the XML tags, I would use it again. It has some built in features (such as callouts: http://www.docbook.org/tdg/en/html/callout.html, multiple output formats from same source, etc.) which make it attractive.

All the XML tags do slow you down so for shorter articles where I don’t need all these features, I stick with Markdown or reST based stuff. It should be possible to convert from any format to any other so I’m not worried about being locked-in. Also look at Sphinx (http://sphinx.pocoo.org/index.html) – it is reST based and was written for the Python language documentation. Looks like it can even do multiple output formats.

]]> By: Stefan Kleineikenscheidt http://blog.reverberate.org/2009/07/30/the-perils-of-writing-good-documentation/comment-page-1/#comment-1414 Stefan Kleineikenscheidt Fri, 31 Jul 2009 09:36:48 +0000 http://blog.reverberate.org/?p=250#comment-1414 Hi Josh, I was faced with the same problem a couple years back. Back then I put all documentation our new and shiny Confluence Wiki, but found out that the export wasn't very good (read: unusable). As a result of this, I started to develop the <a href="http://www.k15t.com/scroll" rel="nofollow">Scroll Wiki Exporter</a> for Confluence which exports trees of wiki pages to DocBook or PDF. That way you can work on the documentation collaboratively and have means to further process you documents (based on DocBook). For both Confluence and Scroll free community editions are available. -Stefan Hi Josh,

I was faced with the same problem a couple years back. Back then I put all documentation our new and shiny Confluence Wiki, but found out that the export wasn’t very good (read: unusable).

As a result of this, I started to develop the Scroll Wiki Exporter for Confluence which exports trees of wiki pages to DocBook or PDF. That way you can work on the documentation collaboratively and have means to further process you documents (based on DocBook).

For both Confluence and Scroll free community editions are available.

-Stefan

]]>