Web Content for Documentation
For official and community-based OpenStack documentation, we have gathered requirements from all Stackers to help in the selection process.
For official documentation, we'll establish docs.openstack.org. Based on the requirements list below and the existence of API docs in DocBook, we have settled upon docbook as the source file, with the plan that RST or markdown can actually be a source and DocBook serves as an intermediate format. RST does not currently support translations within Launchpad but with the next version of Sphinx (1.1) they're moving a step in that direction, towards gettext-based translations.
The docbook source files will be housed and checked in and out of a source control system. The docbook will be transformed to both PDF and HTML with comments using the http://wiki.docbook.org/topic/WebHelpGsoc2010. This proposed solution follows a pattern seen in other open source projects, such as http://doc.php.net/php/dochowto/ and http://www.postgresql.org/docs/8.2/static/docguide-docbook.html, but it will also afford us a polished professional look similar to Amazon's Web Services documentation library (which is sourced in docbook as well, interestingly.)
A page template specification for the docs.openstack.org site is now available in an Open Office document (.odt) OpenStackDocPagesSpecification.odt.
Requirements
Here is a list of requirements, not sorted by priority:
- Content accuracy highest priority
- Content must be available online
- Content must be indexable by search engines
- Content must be translatable
- Content must be re-usable as much as possible, such as include snippet and/or output for use in user interface like an install program
- Link maintenance - Links must update with little manual maintenance to avoid broken links and link validation; redirection preferred
- Must provide versions of technical content specific to version of product
- Authoring should be allowed in open source, non-proprietary tools
- Provide technical content in PDF, html, video, audio
- Internet connection not required to view help that is provided with the package
- Support many content authors concurrently; ideally with diff tool and merge capability
- Content must be searchable
- Content should be easily crosslinked by topic and type
- All content versions need to be comparable (diff) across versions
- Enable comments; ideally threaded discussion
- Enable page ratings
- Enable web analytics
Possible Platforms
Restructured Text / Sphinx - This platform is already in use for nova.openstack.org, swift.openstack.org, and glance.openstack.org.
MoinMoin - This platform is in use on this wiki. It's a Python-based wiki. It does not offer a good commenting solution.
WordPress - This platform is in use on openstack.org but that site is moving to Silverstripe. With permissions set up, we could collaboratively author on a WordPress platform.
Silverstripe - The openstack.org site has moved to Silverstripe, and our first edition of docs.openstack.org may use Silverstripe as well, but with the docbook to webhelp solution, a CMS like Silverstripe is overkill. We basically just need to serve web pages.
MindTouch - This platform is an open source wiki/web CMS at its core called DekiWiki, but with professional support and hosting provided by MindTouch. This platform is in use at developer.mozilla.org.
DocBook to webhelp - This XML standard is well-known in open source circles and can output both PDF and HTML.
Translation Details
Ideally our RST source could be translated, but we need to wait for a 1.1 version of Sphinx for gettext-based translations. According to Jim Campbell, an Ubuntu writer, "There does appear to be one additional caveat with regards to translations. A member of our group filed this bug ( http://bitbucket.org/birkenfeld/sphinx/issue/561/configuration-option-store-translations-in ) in the python-sphinx bug tracker. It appears as though the current gettext-based translations in use by Python-Sphinx may be somewhat non-standard."
MoinMoin enables translation on each wiki page. Here's how you add a page in a translated language.
Mark each new page with its language, by adding a line like "#language:en" to the very top of the page (replace en with the appropriate ISO language tag). Also, add lines ##master-page:NameOfMaster and ##master-revision:number. This last is the revision of the original page for which this translation is up-to-date. Instead of revision, you can use ##master-date:timestamp, where timestamp is the the time of the master page last change. You see this time on the info action of the master page or on the "Check Translation" output.
Order is not important — but all #xxx lines have to be at top.
Example (Danish translation "HjemmesideSkabelon" of the master page "HomepageTemplate"):
##master-page:HomepageTemplate ##master-date:2001-11-30 21:30:20 ##master-revision:10 #language:da == Dit Navn == Email: dig@dem.dk ... ---- KategoriHjemmeside