CMS reference guides: Simple, low-tech problem solving

Simple solutions can sometimes go a long way. Here’s one way we solved a few recurring issues in our development process with a simple solution.

Whenever we do client work, we typically build customized content management systems so clients can manage their own apps. Aside from a few general guidelines, we don’t define the CMS to our clients in great detail. No formal diagrams, write-ups, or discussions. It is far more agile and iterative compared to the much more stringent definition we put on the public-facing site.

Because it’s so iterative, building the CMS gives us a chance to understand the site’s data model as we go. We can learn-on-the-job. The CMS becomes the documentation. We learn from the perspective of real data and real relationships, and how they ultimately surface on the public site. Whenever I’m building a CMS, I feel like I completely understand what’s going on with the site.

But, how can you translate this good feeling to clients and, perhaps more importantly, to the non-technically-involved folk in the company? One success we’ve had recently is having our client contact (in our case, Ian) build reference guides – simple screenshots of the public site marked up with some labels and a legend. Here’s an example below:

The reference guide is on the right-margin of each CMS page

On a couple of our recent CMS builds this year, we’ve had Ian take screenshots of each distinct page on the public site. After I’ve developed add/edit pages for a particular piece of data, Ian can then create a legend from the screenshots and map the fields in the CMS to how they relate to different areas on the site. A simple reference guide is born. Now we’re killing a bunch of birds with one stone. It’s a pretty low-tech solution that accomplishes a few common tasks in web development:

Reference guides keep non-developers up-to-speed with site development
Ian now gets immediately familiar with how all the parts of the site relate to the CMS without doing any direct development. He’s far more equipped to help out our clients because he learns about the entire application through building out these reference guides. It reduces us having to set up quick meetings to discuss the site’s progress.

Reference guides give us an early opportunity to QA
Also, it gives us a good check and balance. Ian can point out things that are missing, or things that seem confusing. It gives us an early opportunity to QA the CMS and dynamic portions of the site. Ultimately, this means the client gets something far more refined the first time we hand the CMS off to them for testing.

Reference guides are a much simpler replacement for documentation
At the same time, the client has fewer questions. The reference guides replace (and, I’d argue, outperform) formal documentation. Reference guides give you the information just-in-time, just as you’re editing or adding a record. We’re not trying to fly a spaceship or program a VCR (on a sidenote, have you noticed all the analogies for “difficult to use” are antiquated?), so our instructions shouldn’t require that much verbage.

Reference guides are a low-tech solution
The best part? Reference guides are just an image and some text. We could go further – click an area of the guide and have it focus on the corresponding element on the page – but, it’s not all that necessary. The low-tech solution solves the majority of the solution without spending a ton of time.

Sometimes, real solutions don’t need all that much pizzaz.