It has been a while since I’ve been on radar, but with Drupal 7 fast approaching and Drupal living in the White House, we need to keep focus on one the keys to Drupal domination: documentation. Here is a little status update on where the Drupal docs world is these days and what’s coming up next. (As an aside, I’ve been distracted from Drupal for a little while due to other things going on in my life, but hope to jump back into the fray by the end of the year.)
Where are we?
Currently our two main projects are working on the new information architecture (IA) and getting Drupal 7 documentation ready. A lot of people have been plugging away to keep things moving.
Drupal 7
We are determined to make sure we have solid documentation for the upcoming, awesome, Drupal 7 release when it finally breaks free. We have a Community Initiatives page set up to coordinate the work to be done. So far work on new installation and upgrade guides is under way, as well as getting the core module handbook pages updated. There has been ongoing work with a whole slew of core doc sprints to keep hammering at core documentation as well in the form of patches for help text and writing documentation for all of the core changes that have gone in.
Information Architecture
We’ve decided to use a task-based approach with the docs, following the concepts behind DITA (note that we are not implementing DITA XML, just the concepts of topic-based authoring). We are moving forward on the IA work by focusing on one handbook initially and making that a “guinea pig” to work out our process and test out some of our theories on the final way we want to structure things. Our Theme Guide was chosen as the victim and an awesome group of folks went through the entire Theme Guide handbook on Drupal.org and tagged all of the pages with information about what kind of content it contains. I have since gotten a database dump from Drupal.org so that we can easily extract that info and use it as part of the new IA process.
Around the corner
With a lot of momentum behind us, we have a lot things planned for the next few months. We will continue our two main projects, of course, but in addition we have plans for a new documentation sub-site and starting up a new way to get people working together on docs. Here is the lowdown on what’s coming.
Drupal 7
We need to keep the work going full steam ahead on Drupal 7. Now that we have hit code freeze, it is time to push into high gear. The “final” freeze for Drupal 7 will be the string and UI freeze on December 1. At that point we will be able to take screenshots and make sure that our documentation is using all of the correct phrasing from Drupal’s interface. We need to keep in mind that any doc changes in core have to go in before that date. For the handbook, in addition to finishing the installation and upgrade guides, we need to also make sure that we have the basic information for creating a new site, which means updating the equivalent of the existing Drupal 6 guide. With a totally new UI in D7, our work is cut out for us. We also have plenty of API work to do. You can see a full list on the Drupal 7 documentation community initiatives page. We will be planning more sprints to focus on Drupal 7, so you can keep an eye out on our group page for the where and when of them.
IA
With our data gathered on the Theme Guide, Becca (our IA lead), myself and few other keen folks will sift through the information and plan out a the best way to organize it. This work is best done by a small group of people, and in the meantime we will open up the rest of the handbooks for tagging, just like we did with the Theme Guide, so we can keep that important prep work going. Once we have a plan mapped out, and a rough structure set up for it, we will need a larger group to review, edit and move the existing Theme Guide into the new IA on a scratch site. From here we can decide what changes need to be made to the plan, as well as begin to create a list of new processes and tools that will be needed to ease the transition and allow us to maintain it long term. After we’ve taken the Theme Guide all the way through and refined the process, we will do the same with the rest of the handbooks.
A new Drupal.org sub-site
In the midst of the Drupal.org redesign, we have also decided that the documentation will be split off into its own Drupal.org sub-site (similar to how groups.d.o and localize.d.o are their own sub-sites). The infrastructure for this was put in place during Drupalcon Paris (big thanks to David Strauss for getting me going) and once we get some things set up, we will be able to use this new site to test out the new IA work, new modules and generally start playing around with creating a home for our docs that caters to our needs.
Peer and Mentoring
Open source is about people and getting people to work together is key. I would like for us to get a core group of people to start working on coming up with a plan for making this easier, and to sort out what processes and tools we can use. There are two main things that we need to address: new people coming in and communication between coders and documenters. I’ll have another post coming out where I discuss this in more detail, but providing a way for new folks to contact the right people to get them started and encouraging coders and “docers” to work together in the skills that they excel with, are key to sustainable documentation.
Ready, Set, Go
Whew, OK so we have a lot of things on our plate. These are exciting times and there is plenty of room for people to dig in and get their hands dirty. Our top priority for right now is Drupal 7 and you can get a jump on the next, best release of Drupal by helping out. Check out the list of things to do, dive in, attend a sprint, and feel free to stop by our IRC channel if you have questions. If you are interested in working on the peer and mentoring work or the IA stuff, stay tuned and there will be more info on those coming within the next month.
RockTreeSky 