The top priority in the Drupal documentation roadmap that was published earlier this summer was to reorganize the information architecture (IA) of the handbooks to make them easier to use and maintain. Becca Scollan volunteered to take the lead and she has been researching and building out a plan of attack. We are now at a good stage to start doing some work that the whole community can engage in. Instead of trying to tackle the whole thing, our first foray will be limited to the Theming Guide handbook only. We are going to begin looking at and tagging our existing content with an eye towards a new way of thinking about it. We have added some new vocabularies to just the pages in the theming handbook and we need folks to go through and assign terms. Instead of just random tagging, we need to keep some overall concepts in mind. There are guidelines that can be referred to, so that the terms we use will be most useful for the following steps in the process.
For a quick overview of where we are headed, we are looking to move our documentation into a topic-based system. This is using the underlying theory behind the Darwin Information Typing Architecture (DITA), even though we aren’t using the XML itself (at least not for now). The general idea is to present information with some structure, having each piece of content be focused around a “topic.” The core DITA topic types are tasks, concepts, and references. As content is written in this manner, you can then use a variety of maps to display the topics in ways that make sense for different use cases. Before we can dive deeply into this for the Drupal handbooks, we need to see what we have and how things may or may not map out. The new vocabularies allow for freetagging, but we are also looking to categorize the content into these core topic types. You can read a bit more about this on the guidelines page.
I’m excited about this work, not only because we are starting to get our hands dirty, but because this will be valuable experience as we start to learn about and rethink conceptual models of how documentation gets done. If you want to help out and learn as well, please review the guidelines, ask questions and dig in to the Theming Guide. We will have an open question and answer period in #drupal-docs on IRC, on the Freenode network, at 2 p.m. EDT (find your time) on Tuesday, August 18. If you can’t make that meeting, feel free to catch myself (add1sun) or Becca (beccascollan) on IRC at other times, or you can create an issue in the documentation issue queue.
Cross-posted on groups.drupal.org.
RockTreeSky 