This is a crosspost of the wiki I create at http://groups.drupal.org/node/109119 In February LeeHunter posted his wish list of features for "an awesome technical communication CMS". I've copied his list and processed the comments in the discussion and some of my own, and added our current status implementing these features and ideas of how any missing features could be implemented in the near future. I'm very much aware that in the coming months most documentation efforts will probably go into getting the documentation updated for Drupal 7, and it's strategically a bad idea to at the same time change from a freeform format to a structured documentation format, rebuild the infrastructure and do a mayor content update. Nothing prevents us however from dreaming up the ideal infrastructure, and if I know what the doc team is dreaming about, I might be able to steer our (Pronovix') work on the DITA documentation system into that direction ;) There might also be certain technologies that could make the documentation upgrade less painful (e.g. using the versioning system mentioned below). There is a wiki on groups.drupal.org, so please add your suggestions! ************************* VERSIONS - Instead of having separate files for every version of Drupal core, it would be way faster and easier to manage if we could have 1 document, with specially marked up sections for the different versions of Drupal. You could still split the display for the documentation in different tabs. This would significantly reduce the work on future core upgrades.
- Ready: this is part of the DITA standard, displaying it would be a matter of using different XSLT's. We (Pronovix) have built a UI for this in Spezzle before using RDFa markup in the semantic filters and layers.
IMPORT TOOL - Ability to import XML-based content in DITA, DocBook, or custom formats. Able to monitor file folders or external databases/repositories for changed content and synch automatically or on demand.
- Ready: We can now import content in DITA as individual file upload and by monitoring a file folder using our feeds extension, this could be used to import from a folder on the Drupal site in which you checkout a GIT repository.
- Future: Using CMIS it should be possible to connect to Sharepoint, Alfresco and other document repositories. For Drupal.org that would however not immediately useful.
AUTHORING TOOL - WYSIWYG interface for creating and editing schema-compliant content. The writer can easily apply tags to content (but only the permitted tags for a given context!). The author can be given suggestions and prompts. There is a mechanism for conditional text (i.e. the writer can tag text and images so that different versions can appear in different publications). All this would require a lot of JQuery love to be usable.
- Ready: With poorman's DITA users can create valid DITA without getting lost in the markup options.
- Selective enrichment WYSIWYG: We would probably want to have some basic WYSIWYG editor that lets users add a subset of the attributes and sub-elements of the main elements inside the CCK fields. A full fledged WYSIWYG editor that is capable of implementing the full DITA spec and that is still easy to use for beginners would be an epic project.
- full WYSIWYG: My colleague Yorirou has an idea for a technically achievable editor that would be able to deal with any type of XML specifications.
PUBLISHING/EXPORT TOOL - Provides drag-and-drop interface for organizing content into single sourced publications (i.e. the same chunk can appear in many places). The publications can be web-based, PDF, XML, online Help etc. Different versions can be built using tags and conditional text.
- Ready: We've made a system that transforms the .mm format mindmaps from Graphmind into DITA maps (XML), that are in DITA the basis for making documentation from the "single source" topics. We've also implemented an export functionality that uses the DITA Open Toolkit to export to PDF, XHTML, archive, etc. With this system it's possible for users to create their own "Complete guide to building an xyz site" outlines
- Future: Right now the mindmaps are not validated in the UI against their DITA map convertability (it's possible to create mindmaps that will fail conversion). It would be nice to have input validation in the UI. There are some other modifications to Graphmind that would make it easier to manage documentation (e.g. create new documentation topics from Graphmind, being able to edit topics in the map, etc.)
DOCUMENTATION CLIENT & SERVER - Let's you use and update documentation from inside a Drupal installation context. This feature would make it easier to bridge the gap to end-user documentation in individual projects. This could do for the documentation team what the localization server and client did for the translations teams worldwide.
- Proof of concept: We've got a first proof of concept for a documentation server that lets you connect specific form elements in your installation with help topics on the documentation server.
- Future: Advanced help and Help Inject make it fairly easy to package and reference help topics with html files that can be shipped with an installation. In the future it would be great to export all the help topics for a specific project into a help feature that than makes these topics available in their respective contexts.
MEDIA INTEGRATION - As the thecontentwrangler mentions in his comment video and interactive media are very important (e.g. heather's presentation in Drupalcon communicating drupal visually).
- Ready: Technically this is solved, we would need to decide what content we would want to agregate from where and how.
REUSING EXISTING DRUPAL CONTENT - As Andyoram mentions in his comment there is a lot of documentation snippets out there spread across all the Drupal blogs that are currently only searchable with Google. We should be able to map these snippets from the documentation site and possible reuse them in more extensive documentation topics.
- Ready: with prepopulate it's easy to make a bookmarklet that would let users submit these snippets to their documentation trail on the documentation server.
- Future: We've previously developed faceted insert, a proof of concept for a search plugin that let's you search for nodes on a site using faceted search and than insert the found text into a text area. Right now that works with faceted search, but it should be not too complex to make this pluggable and use snippets from Solr.
INTEGRATING WITH API.DRUPAL.ORG - Currently the API documentation and the docs on d.o. are not really integrated (except for individual in content references) It would be nice to more closely integrate both systems.
- Future: Ideally API documentation would be available as reference DITA topics, maybe there is a way to automatically map the docs to DITA references?
WORKFLOW - We would need to figure out what workflow/permission set will get us the best quality/number of contributions trade-off.
- Ready: Technologically this should be an issue, Drupal contrib has everything we need for this. This is more an organizational issue
SCHEMA - We could make a DITA specialization for Drupal e.g. have a topic type for modules, themes, features and installation profiles.
- Ready: Technically this is not hard, we can use CCK to build a couple of extra poorman's DITA topic types specifically for these purposes and extend the module to transform the form into valid DITA. We however would need to figure out the types of information we would like to include in these forms.
TAXONOMY - With RDFa in Drupal 7, keywords be will marked up in RDFa and sites will become queriable with SPARQL. Now would be a great time to make a central Drupal vocabulary for blogs that write about Drupal, so that the Drupal blogosphere becomes queriable as a whole.
- Ready: Neologism which was developed by DERI is built for this purpose. If we can get this tested and documented, we could have several Drupal shops use the vocabulary once they switch to D7.
FLAGGING - As jhodgdon mentions it would be great if users could flag content in the documentation with flags like "to look at later" or "daily reference".
- Ready: Easy win with the flag module
