Documentation

Goal: Create tools and services for modular reusable documentation in Drupal.

When it is required, site end-user documentation is a laborious overhead. Currently we lack both the tools to do good Drupal site documentation and the infrastructure to collaborate on this with the community. That is why we want to build a Drupal Documentation distribution and a platform that addresses these problems and that makes it possible to:

  • Easily incorporate "living" community documentation into site documentation
  • Incorporate user type specific descriptions in documentation
  • Document implementation patterns and their resulting features and share this documentation with the community

When we talk about documentation we either think about the developer documentation as it can be found on drupal.org or about end-user documentation delivered by a developer when a project is finished.

We however think that there is a lot of value in the combination of both systems. We want to build a documentation distribution that uses a similar approach as the localization server and that enables a distributed/federated documentation architecture for the Drupal project. As a Drupal user you'll be able to get a set of documentation from the drupal.org docs server imported into your own site. You will than be able to edit it and build subsets of the documentation for your own projects. You'll also be able to submit topics that were edited or created by you on your own infrastructure and add them as suggestions to the Drupal documentation server.

You'll be able to export the documentation in the DITA format, which can with the help of the DITA Open Toolkit in turn be transformed into XHTML, Microsoft Compiled HTML Help (aka Windows help or .chm), Eclipse Help, Java Help, Oracle Help and Rich Text Format and PDF through XSL-FO | reference here.

The distribution will use a DITA architecture model with the most important elements of the DITA spec implemented in a mixed fields and markup model. The system will allow wiki-like user editing, will be multilingual and will support the translation of documentation topics.

The DITA distribution will of course not only be useful as a tool to document Drupal: there will definitely be many applications for a Drupal based, collaborative platform for DITA structured documentation. That is why we plan to make the distribution and our service out of the box usable for both Drupal and non-Drupal usage.

For more information about DITA, check out the Wikipedia article.

User stories

User stories Points Priority
As a documentation writer I want to reuse topics from DITA documentation servers so that I can save time and easily use collaboratively created documentation N/A
Your rating: None Average: 4 (1 vote)
As a documentation writer I want to be able to make scripts that automatically generate screenshots of certain elements in a site so that I can automatically generate personalized documentation with screenshots N/A
Your rating: None Average: 3 (1 vote)
As a documentation writer I want to compile dita maps in Drupal so that I can easily collaborate with other users on the documentation of a project N/A
Your rating: None Average: 3 (2 votes)
As a documentation writer I want to be able to work with documentation topics from external resources so that I can use and help building the documentation for drupal N/A
No votes yet
As a documentation writer I want to use a WYSIWYG like interface to work on the DITA xml formatted data so that I can do everything more easily N/A
No votes yet
As a documentation writer I want to make my own version of a centrally stored topic so that I can collaborate with others but still easily add personal preferences to topics N/A
No votes yet
If you have a new user story for this project you can add it here.