ibatis-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Clinton Begin" <clinton.be...@gmail.com>
Subject New iBATIS Documentation Format
Date Tue, 03 Oct 2006 00:44:24 GMT
Hi everyone...

In another thread that wasn't appropriately named, we raised the issue of
the iBATIS documentation formats.  What caused me to reopen this as a new
thread is that someone just recommended APT, which seems very interesting
(read and see below for more).

We'd like our documentation tool to meet the following goals:

Developer/Author criteria -- The following are key to maintaining high
quality and timely documentation.  Developers need to have a low barrier to

   - Accessible / freely available to all
   - Easy / familiar
   - Portable / Available for all desktop platforms
   - "Diffable" / Merge / Compare features.
   - Participative / Community Capable
   - Quick Changes / Deployment

User/Reader criteria -- The following ensure that readers of the
documentation have options.

   - Printable
   - "Bundlable" with distribution
   - "Downloadable"
   - "Browsable"
   - "Searchable"
   - Multi-format: PDF, HTML -- to achieve the above goals.

Alternatives discussed so far:

   - OpenOffice.org -- currently the choice of iBATIS for Java
   documentation.  Excels at accessibility, ease of use, but really sucks at
   participation, quick changes and deployment.  All other criteria are met but
   not exceeded.
   - DocBook -- currently the choice of iBATIS.NET documentation.  It
   excels at "diffability" and multi-format including great PDF and HTML
   output.  But it fails at ease of use / familiarity and therefore
   participation and quick changes/deployment as well.  All other criteria are
   met but not exceeded.
   - Confluence.  Excels at Participative and Quick Changes, but fails in
   many others including Printable, Downloadable, Bundlable.
   - APT: Almost Plain Text.  This would seem to achieve everything.
   It's basically what I would call an offline Wiki-style formatted text that
   can be converted to HTML, PDF, RTF and other formats.  It's free (Apache
   1.1 style license), easy (it's plain text with some rules), diffable,
   easy to change/deploy ("automatable") and could be participative (because
   it's "automatable").  It can output to all of the formats to achieve all
   user/reader goals.  Is there something I'm missing?  Or does it sound
   great?  http://www.xmlmind.com/aptconvert.html
   - Others alternatives I'm forgetting?



View raw message