Making Better Documentation, and Making Better Sites
5 min read
Part of our work for the Knight Drupal Initiative includes work to lower the barriers to getting started using Drupal sites to power community-driven media. As we work toward this end, we have multiple tools at our disposal, including:
- Better documentation, for both site administrators and people using the site
- Easier installs, to allow people to enable more complex functionality with less work
- Easier and more flexible theming
At the risk of stating the obvious, the work we do for the Knight Drupal Initiative will also be immediately transferrable to all of Drupal development.
Getting Started: Journal
The Journal module allows us to keep a running record of changes made on a Drupal site. Currently, it allows you to take notes as you build out your site. It's a great tool to track the specific steps people take as they work within a site.
We will build out two additions to Journal:
1. Tag journal entries, which would allow us to create categories of journal entries. For example, while configuring the WYSIWYG API to work with Filefield and Filefield Insert, we could tag these entries as "Text Editor" -- later, this would allow us to see exactly how the editor was configured.
2. Export journal entries by tag or by date range, in csv, ordered list, or unordered list format. This would allow us to generate documentation on how sites are built. This documentation can be used on drupal.org, for site administrators as sites are delivered, or to create end user documentation.
By way of example, let's say we have built a site that is designed allow teachers to create online portfolios as part of professional development. Prior to delivering the site, we could walk through the steps of creating a portfolio. At each step, we would comment on the process of creating the portfolio using the Journal module. We would tag each entry as "portfolio creation." Then, once all the steps have been completed, we would export the steps as an ordered list, and voila, we have our end user documentation.
Moreover, this process also gives us the instructions and order we need to develop functional tests using Simpletest.
With these additions to the Journal module, we will have the base package for creating more comprehensive documentation about all aspects of building and using a site. However, one of the challenges of documenting a site build is getting the documentation into the hands of end users, or people not directly involved in the build. Often, comprehensive documentation can be overwhelming as it floods someone with information.
Inject Me!
The Advanced Help Injection module builds off the Advanced Help module, and allows us to draft documentation using Drupal's core book module. Then, the documentation can be inserted on specific pages within a site, so people only see the documentation they need when they are at a place where they need it. So, the documentation generated using the Journal module can be presented to people exactly when it makes the most sense.
And finally: Advanced Help Injection allows the documentation to be exported as a module. So, all the documentation can be pushed to code, and delivered with the site. This brings us closer to the goal of having a site that is self-documenting, for both site admins and end users.
Moreover, the process of creating these tools can actually be documented using the tools themselves. While it feels like a blend of eating our own dogfood and chasing our own tail, it works.
What Are We Documenting, Anyways?
In this post so far, we have looked at simplifying the task of creating documentation, and using existing tools to get that documentation to people in a more efficient way. However, documentation assumes featuresets, as we can't have documentation about what to do without something to do.
This is where we cue the Features module. Take a minute to check out the latest post illustrating the power of Features over on the Development Seed blog.
As the video and post shows, the Features module allows us to create bundles of featuresets that can be moved from site to site. We envision a system where two things happen:
- Featuresets are paired with documentation, so that any set of features can be accompanied by inline documentation; and
- The process of creating new sets of features is fully documented using the Journal module, to empower more people to build and share features.
Making It Look Pretty
Theming and design are both enormous categories, so I'll be brief. In parallel with the work described here, we are working with Joon Park to build out a base theme (currently named Annex, but it might get changed to Mango Smoothie for the official release) that simplifies the process of creating a unique look and feel for your site. For end users, it supports some simple eye candy out of the box; as one example, it has multiple block regions, including some that support accordion and tab effects by default. For themers and designers, the process of inheriting features from the base theme to subthemes has been overhauled and simplified, allowing people more control and flexibility in building sub themes. More to come on this; ideally, we will have a release at some point in June.
