Information Technology Dark Side

Struggles of a Self-Taught Coder

Information Technology Dark Side header image 2

Creating a User Guide, the Lean Bootstrap Way

June 12th, 2012 · 2 Comments

If You Need a User Guide You Have Already Screwed Up
This is a pretty commonly held belief among designers, and it rings true because there is some truth to it. I would amend this platitude to read as follows:

If you need a user guide BECAUSE YOUR SOFTWARE IS HARD TO USE, you have already screwed up

I have resisted multiple requests to provide my TroopTrack users a user guide over the last four years for exactly this reason. When my users asked questions, it was mostly because parts of TroopTrack were poorly designed. So, most of the time, instead of writing a user guide, I would simply use their input to guide a re-design of the feature in question. This was educational for them and for me, and it was absolutely critical in the learning-process as a product owner for me. This back and forth design cycle between the users and myself helped me to understand their problems well enough to build a product that is, in my opinion, the best scouting software on the planet.

There are Other Reasons For Needing a User Guide
I frequently call trial users and ask them how things are going and if I can help them get started. Perhaps this was just a freak coincidence, but two customers in a row told me the exact same thing:

Your software looks nice but we went with because they have a user guide.

These interactions taught me that there are other reasons for having a user guide that have nothing to do with software design.

  • Reason #1: A user guide is frequently an important item on the evaluator’s checklist, whether your software needs one or not. Not having a user guide often means they won’t even consider your product.
  • Reason #2: Purchasers of scout software have to convince a committee that my product is the right one and the lack of a user guide makes that a more difficult task.
  • Reason #3: A user guide is often perused by potential buyers as a way of seeing what your software is able to do for them.
  • Reason #4: No matter how well designed your software is, some users prefer learning through demonstration over learning through experimentation. Those users need a guide, or a video, or something.

Why You Should Just Roll Your Own User Guide Infrastructure
There are solutions out there building wikis and user guides etc. Some of them are free and many of them are not. I’ve tried lots of different things over the years, including:

  • RedMine – too painful and ugly
  • ZenDesk forums – forums aren’t user guides and users leave my site
  • Atlassian Confluence – lovely but expensive
  • Comatose – the gem is dead, unmaintained, and stale
  • Refinery CMS – I don’t want a separate admin tool for help pages (otherwise I lourve Refinery CMS)
  • ActiveAdmin + Awesome Nested Set + CK Editor – User guide bits and bites delivered in less than an hour!

I already had active admin, and it’s super easy to add CK editor to active admin forms, so all I had to do was create a simple model with a title, body, and the ability to nest pages. With Rails, I was able to do that in about a half an hour, but I rounded up to an hour cuz I don’t want to seem vain. :)

What About the Content? Let the questions be your guide
I use ZenDesk for my support tickets, and about half of them are questions. I’ve fallen into a pattern with these support tickets that I think is very lean. Here’s an example:

Hi John,
Based on your question, I put together a new page in the User Guide this morning to show how to edit user info such as birth date and phone number. Here’s a link:

Please check that out and let me know if it doesn’t work.


Dave Christiansen,

I like this approach because it doesn’t duplicate effort and I know the content is needed. The problem with this is one I experienced when I was trying to use ZenDesk forums in the same way – it’s easy to end up with an unstructured mess unless you give the user guide a structural smackdown as you go.

I started out with a skeleton that mimics the structure of my application. This is a pretty common approach and let’s face it, there’s no huge need to be innovative here. A user guide that is structured like the application is pretty intuitive. It might be more artsy to write it like a novel, but … (Oh, hang on, I find myself tempted to try that).

A Page a Day Keeps the Wrackspurts Away

I went on a bender one weekend and wrote about ten pages in a day. That drained me of all energy for writing for about a week, and I suspect it is not a sustainable way to do it. I’ve since switched to a page-per-day approach. Sometimes I will write more if I have user questions to answer, but if I don’t I stop myself at one. At one page a day I will have a fairly comprehensive user guide by the end of June.

Don’t Over-Invest, Mis-Invest, or Pre-Invest
A few years ago I was part of a project that hired a technical writer to write a comprehensive user guide. We paid her thousands of dollars and she did a very nice job, but I’m not sure the user guide was ever really put to much use. We still got lots of questions that weren’t covered by the user guide, and our customers started asking for the ability to customize the user guide for their particular policies. We had over-invested, mis-invested, and pre-invested in the user guide. All of these were mistakes.

The meaning of over-investing is probably obvious. Spending more on a user guide than is needed. Mis-investing and pre-investing may not be so obvious.

Mis-investing is spending your user guide investment on the wrong things. Our tech writer set out to cover every single feature of our software, from logging in to logging out. There were lots and lots of pages that I reviewed that merely re-stated what was obvious from the user interface. This was a mis-investment.

Pre-investing is spending your user guide investment BEFORE your product is stable enough to be documented inexpensively OR before you really know what users are confused about. Pre-investing and mis-investing usually go hand-in-hand because you are GUESSING what documentation is needed and you are going to be wrong some large percentage of the time.

User Guides Can Be Good Investments if You’re Careful
Needing a user guide doesn’t necessarily mean you screwed up. But you should be certain that investing time and money into a user guide is the right thing to do. It is very often the case that you should be fixing your crappy software instead. That was definitely the case with TroopTrack for several years, and even now I don’t try to “user guide” my way around a feature that is poorly designed. I just fix the feature.

Also, don’t spend money on user guide pages you don’t need. Let users show you the way so that you don’t mis-invest. Only add pages you imagined up to meet a marketing or structural need.

If you’re curious, you can check out the user guide infrastructure I cooked up for TroopTrack (in less than an hour!) here:

If you enjoyed this post, make sure you subscribe to my RSS feed!
Stumble it!

Tags: Uncategorized

2 responses so far ↓

  • 1 Anthony Panozzo // Jun 12, 2012 at 10:56 am

    Fantastic post Dave! I really like the professional look and feel of the user guide.

    My biggest question or what would hold me back from creating a user guide of my own would be: how do you update the site reliably without needing to always update the documentation, or is this just a necessary evil? I’m thinking something like an app driver that would take screenshots and annotate them, and would let you know when the interface changed enough that you couldn’t navigate to what you wanted to navigate to. But maybe there is an easier solution. Thanks!

  • 2 David Christiansen // Jun 13, 2012 at 9:42 am

    I think the best way to keep the user guide up to date is to just include it in your normal workflow, just like the tests. If you change a feature, you also update the related user guide, etc.

Leave a Comment