Revision as of 08:21, 20 June 2008

Overview

• Find an alternative to our current xmldoc + doc_builder custom solution to edit, maintain and publish up to date documentation.
• Provide a way for user to contribute.

Requirements

• Editable by specified people.
• Flexible enough to support the kind of typesetting we need for Eiffel texts; in particular it must be possible to define an EFF filter that produces documentation from

contract or interface views.

• Flexible enough to support easy inclusion of pictures
• Can easily be hosted on a new site (eiffel.com, origo, mirror sites....)
• Most likely Wiki-based.
• Compatible with Subversion [1]
• If possible, can be automatically translated to a format readable locally [2].

Notes:

• [1] I am not sure how critical this requirement really is since Wiki mechanisms have their own history and recovery facilities.
• [2] Desirable but not essential. If other criteria force us to go to a Web-only form of documentation we'll have to accept it. We lose people who write programs in a plane but that's about it.

Looking for THE solution

There are basically two families for online solutions:

• CMS
• Wiki (which are specialized CMS)

Importing current documentation

In any case, we need to find a way to import our current documentation into the new system.

For now we have well formed XML content for our documentation, so this should not be that difficult to convert it to any other XML format (including DITA, docbook, ... even wiki syntax ...).

• In the best case, the conversion is fully automatic
• In the real life case, we might need to manually edit some parts
• In the worst case, we convert the documentation by hand copy/paste ... with eventually some tool to convert partially the content.

Exporting content

Then depending of the solution, we might have

• only online access
• export content into
  • HTML
  • PDF
  • XML: which would allow us to convert to docbook or dita, and then generate HTML, PDF, CHM, ...

Final considerations

• We can then the "export" content into our subversion repository
• I think, this is critical to have a way to export the content into well formed data, since later we might need to go for another solution (in a few years). So we don't go into a "one way" solution.
• Since most of the time wiki are also CMS, I won't do the distinction anymore

Potential solutions

There is no real order.

(1) “DocBook Wiki” (http://doc-book.sf.net):

   this is a wiki based on docbook, the web front end allows to edit the docbook content directly in a user friendly way (at least it tries).
   The advantages is to manipulate directly docbook (which can be  converted to any output format).
   I tried it, but honestly I prefer to use doc_builder rather than docbook-wiki ... that is to say, I wouldn't go for doc-book wiki.

(2) Drupal's book (http://drupal.org)

   Drupal is a powerful and flexible CMS (used by eiffelroom, origo, ...) and it has a nice "books" module which allow the users to write a "books" (structured content), so this is adapted for documentation.
   However there is not yet any "ready-to-use" module to import/export the books' content.
   There is a user contrib module for that (unfinished for now). I contacted the maintainer, but he told me he wanted to "release" a new version beginning of june, but this can be end of june, or even later ...
   Since we want to take a decision pretty soon, we should forget about this promising solution.
   Or, we can implement our own module for that, but this implies learning the drupal API , installing a configuring a dedicated drupal for this purpose.
   But this can be done, and this would allow us to benefit from drupal's ease of use, and being able to improve it later.

   More details later ... but from what I understood, the "upcoming" module does the following
      - take the page content (usually text or text with simple embedded HTML)
      - use a tool to generate a docbook format from this text (it converts the HTML into xml docbook XML, I guess the html needs to be well formed ...)
      - to do that, it requires to install a few linux tools (including pdf tools, xml, docbook converter, xslt ...)

   Note: we can always use the wikitools module for drupal which has wiki syntax similar to mediawiki (cf Origo's wiki)

(3) Daisy CMS (http://daisycms.org/)

   Daisy is a content management system that offers rich out-of-the-box functionality combined with solid foundations for extensibility and integration.    
   I will tell you more about this one, since I recently discover it but it seems quite good
   - online editing (via wiki)
   - import and export functionalities
   - API, and also remote API, which could be useful to build an offline editor maybe ...
   - http://cocoondev.org/daisy/features.html

   I need to install and test it, but it seems quite nice

(4) Mediawiki

   pro: - we already use it for dev.eiffel.com
          - it is well known and maintained
   cons: it does not have very structured content

(5) Twiki

   This is a structured wiki -for enterprise- with many plugins, but I haven't found any to export to XML format, or any offline format.
   Otherwise this is a nice wiki,
   - based on perl  (I don't really like perl because of the admin part, however for a web site ... why not)
   - with its own wiki syntax (different from mediawiki)

(6) dokuwiki

   - based on php
   - using plain text files for content storage. So it is easy to commit in subversion, and I guess easy to scan/parse/generate XML output
   - wiki syntax is different from mediawiki
   - plugin: (http://wiki.splitbrain.org/wiki:plugins)
           - Open Office Export
           - Dokukiwix: Generates a static HTML, offline browseable version of your Wiki
            - pdf export
   - http://www.wikimatrix.org/show/dokuwiki

(7) pmwiki

   - php
   - simple and light
   - many plugins
   - really nice PDF export output

(8) Moinmoin wiki

   Used by many big open source projects, and they seems to be able to generate PDF, and so on ... but I haven't found yet how, but I didn't have time to investigate deeply yet.
   And I read that for instance debian export their wiki content to docbook and then to html, pdf .... (need to be verified)
   TO BE EVALUATED

(9) wikibooks (mediawiki)

   - http://en.wikibooks.org/
   - the various books are available as PDF, so there is a way to export to PDF
   - but I don't know if wikibooks is a product by its own, or a mediawiki customized for this purpose. I think this is rather a customization
      so we might find how it is done, and port this to our dev.eiffel.com...
   - check: http://en.wikibooks.org/wiki/Special:Version

(10) build our own solution

   - web server + goanna + eiffel + XSLT + ....
      but I think we want to avoid building another internal product which has to be implemented, maintained, and improved ...

to check point by point our requirements

   - Editable by specified people.
     
             This means ACL (Access Control Layer), most of the solution provides that, except mediawiki (maybe using a plugin)

   - Flexible enough to support the kind of typesetting we need
     for Eiffel texts; in particular it must be possible to
     define an EFF filter that produces documentation from
     contract or interface views.
  
             That's a difficult point, not all solution provide syntax highlight features ...

   - Flexible enough to support easy inclusion of pictures
  
              To include picture, usually CMS or Wiki are not that flexible. I mean you need to first upload the picture, give it a name, and then reference it with specific syntax.
               Using drupal and a specific plugin, this is easier since you can choose from a "catalog" of uploaded file.

   - Can easily be hosted on a new site (eiffel.com, origo, mirror sites....)
           
               Depending of the solution, it can be either simple using php, or more complex when it deals with python or perl, and provide PDF export and so on, since you need to install specific tools on the linux hosts (usually those advanced features requires linux)

   - Most likely Wiki-based.
  
               Wiki or CMS ... this is not the main point. User might like a WYSIWYG, or at least advanced editing (but most tools provide one or the other)

   - Compatible with Subversion [1]
  
               We just need to find a way to store either the content, our an output into plain text file (XML or wiki ...)

   - If possible, can be automatically translated to a format readable locally [2].
  
               Here again, there are solutions either using XML or HTML or PDF ...

• I would just add the following requirement

   - Being able to migrate from current "doc_builder" documentation to future solution, and then from future solution to any solution (in case we need to migrate to another system if the next years)

Key criteria

• 1. Ease of import from existing documentation (xmldoc, or HTML)
• 2. Ease of import from EiffelStudio (from ec's generated content)
• 3. Ease of editing
• 4. Ease of output generation (offline):
  • 4.1 HTML
  • 4.2 PDF
  • 4.3 XML
  • 4.4 Others?
• 5. Stability of the solution, size of community, user support, how likely is it to be around 10 years from now...
• 6. Free or not
• 7. Ease of getting out if we change our mind (i.e., how much are we locked in our choice?)

Tools to be considered at the moment (short list): Drupal, Daisy CMS, MediaWiki.

Here should come a comparative assessment of these solutions with respect to the criteria given.

Temporary conclusion

• To compare those wiki solutions: http://www.wikimatrix.org/compare/Daisy+DokuWiki+MediaWiki+MoinMoin+PmWiki+TWiki
• Note: quite often, it is said XML (or PDF) export available, but this is for the current page only which is not that convenient for our case.

However when this is XML exporting, a least we can automatize the export for each page ... and rebuild the whole "book" after.

For now, I keep testing and evaluating tools. It takes time, since I have other tasks.

My first feelings would be

   1) Daisy CMS, if it really does what it says
   2) Mediawiki + plugins .. need to find them. Of course we could go for other wiki, but I am worry to use too many wiki syntaxes
   3) Drupal + existing modules + our modules   (require developments...)

Last point, at ISE, we are already using

• mediawiki (dev.eiffel.com + internal site),
• drupal (eiffelroom, origo, testing, ...)

In my opinion, we should not add one more tool (unless we find THE perfect solution). But it is better to keep our knowledge focused on our current tools, rather than maintaining another tool (especially if it implies new technologies, since it means extra maintenance, security issues...)

So I would favor to go for Drupal CMS, we might need to code more things our self, but in the final this might be easier. In any case, we need to code importer from our current doc, and also from the output of EiffelStudio. Mediawiki is another solution, but I don't find it very user friendly, the code is dirty, and not very easy to extend even with third party extensions).

Comparison of potential solution