Iterating towards the ideal documentation theme for WordPress

A month or so ago, Joe and I started working on a dedicated documentation theme for the J-School’s Tech website. We’re calling it Documentation Redux, and it’s currently at v0.3. Closer to v1.0, we’d like to generalize it and make it available for others to use. For now, I want to review where it’s at and articulate where we’re trying to go.

Our goal for the website is simply to publish and make accessible as much knowledge as we can. For every support ticket possible, if a relevant explanation doesn’t already exist, we want to make sure the answer is captured on the website first, and then just include the link to the documentation in our response. The theme will evolve with this goal in mind.

Homepage as the primary entry point

On the homepage, we make search, the dominant information retrieval paradigm, as prominent as possible. I’ve implemented Sphinx as the index utility, which means results are returned against a relevancy ranking instead of reverse chronological order (WordPress’ terrible default).

The primary content area is widgetized into two columns. Instead of manually updating HTML lists of links, any admin user can manage what shows up using widgets or menus.

In the right rail, we’re showing the most recently published blog posts and the most recently updated pieces of documentation. This is our activity feed, per se. At the top, if a user doesn’t find what they’re looking for, they can always file a new support ticket.

Across the header, users can navigate content by any of the seven custom taxonomies we have: topics, courses, contexts, hardware, software, WordPress plugins, or WordPress themes. All roads lead to Rome. The big idea is to have a bucket of structured content from which we can create new packages on the fly (related). For instance, if we needed to create a cursory introduction to new professors, we could create a Context term called “Incoming Faculty”, associate all of the content we need, and email them a link they could bookmark, print, download as PDF, etc.

Taxonomy term views bundle discreet pieces of content

It’s still a work in progress (look at WordPress for an example). The challenge is fitting all of the pieces together on the fly. Ideally, a term landing page has a short introduction, a clear listing of the documentation available, relevant statuses, asides and standard posts from the blog, and names and avatars for the staff members who can help in a pinch.

Specifically for the last bit, we’ve created a custom post type for staff. They can be associated with taxonomy terms just like posts and pieces of documentation. The problem we’re trying to solve is students (and faculty and other staff) not knowing who to go to for questions on any given term. I’ve lost count of how many times I’ve been asked whether I know the answer to a question about Flash.

What the future could bring

As with many projects, the list of features we want to add is just as long as what we’ve already done. In particular, there are a few I’d like to identify.

Reminders about stale documentation. Each piece of documentation can have more than one maintainer thanks to Mo’s nice Co-Authors Plus. Unfortunately, it’s hard to keep track of what exactly is out of date when you have a large body of content to maintain. Either through a custom plugin or as a feature of the theme, it would be nice to have a post meta box where you could set a reminder date. On that date, it would send you an email and/or surface an interface nag to spend 5 minutes updating the piece of documentation.

Auto-refresh search on the homepage. Much like Google Instant, typing into the search box on the homepage would bring up results right away. As you typed, the results would dynamically refresh. 37signals has this too on their documentation site and it’s quite nice. Expanding this, if your query matches an existing taxonomy term, you’d have a lightweight link to its landing page appear at the top of the results.

Link database like delicious. We’re trying to write as much documentation as we can, but we’re not perfect. It would be great to incorporate external documentation and articles as links in our taxonomy term views, make them available in search, and offer multivariate filtering.

“Was this helpful?” and other lightweight feedback prompts at the end of documentation. Capture user feedback on our content as unobtrusively as possible. Authors could A/B test different prompts to see which produce the most valuable input.

Current and historical service issues. As would be expected, we manage a number of technical services with varying levels of reliability. When a service like the little voicemail indicator light goes down, users file support tickets at best and start calling people at worst. Our notification system now is an email to everyone at the start of the issue and another email when the issue is resolved. Ideally, we’d appify all of this so users had a central place to go to if they suspected an issue, we notified affected users only as necessary, etc.

The last one might be a theme in itself, we’ll see. Further ideas, suggestions, criticism or inspiration would be much appreciated.