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.


Andrew Spittle June 7, 2011 Reply

Really interesting stuff. This bit will save so much work and headaches going forward.

The packages of content are an intriguing model for putting together documentation. Sort of like the support equivalent of topical landing pages. Once that model is in place I can see a lot of really cool things growing out of it.

The update reminders are right on. That’s definitely one of the challenges in keeping documentation up to date. For the auto-refreshing search, Media Temple does something similar on their support pages which is pretty nice.

One improvement could be a table of contents up at the top for the longer support pages. Something that provides quick links to the sections down below. It’s helpful for users, but also helpful for you guys as you’d be able to link directly to a section heading (although I do see that you have emphasis running on the site 🙂 ).

Nice work, I’ll be interested to see how this grows.

Nicholas June 23, 2011 Reply

This is really cool! I have been working on a project where I am using WordPress to create a site where professionals involved in the construction of hospitals can discuss documents and issues important to what they do. I am very curious as to how your site works and is maintained in terms of who can create and publish documentation. How do you manage users/writers and flow of creating/editing/updating content?

Right now I am pretty happy with how WordPress handles the site, but there are things that could be better. For example, I have different authors setup, but I have not yet found a way to display only comments relative to articles they have written to be displayed to them in the admin area. Right now, each author would need to “find” their comments amongst all the comments, which is not ideal. Another issue I would like to tackle is instead of having an email each time a comment is made, WP sends through a “digest” of all the comments made on a calendar day. That way an author is not bombarded with comment notifications all day long. But are still reminded that comments have been made. I have found a way to use the comment feed via Feedburner’s Publicize options, but I am not sure this is an ideal scenario.

Anyway, site looks great! I am interested in how it develops.

Daniel Bachhuber June 23, 2011 Reply

Thanks Nicholas, it’s awesome to hear positive feedback on our progress.

With regards to your question, everyone who needs to publish documentation on the site has the ability to do so. We’re pretty loose about our editing workflow, so when you think it’s ready you hit publish. Furthermore, if you come across an article you think needs updating, you make edits and hit save. Eventually, I want it to send out email notifications periodically to remind you to review the content and make sure it’s up to date.

The ideas you express are definitely limitations WordPress has, and would be useful features to develop.

Nicholas June 23, 2011 Reply

Hey, cool. In the end it is better to give people that free reign.
I came across a plugin you may be interested in regarding content being outdated:

Seems to be along the lines of what you mentioned.

I have been looking at the links you posted about search. I’m not going to be implementing Sphinx…but I found an interesting article on Yoast about improving WordPress search. Reading about Sphinx gave me some ideas, so thanks for the info.

Leave a Reply