Documentation-Centric Product Design

While the Movable Type product team has made great strides in making our documentation complete and keeping it up to date, we still have the perpetual challenge of actually getting the documentation ready in advance of the actual release as well as leaving enough time in the schedule to do it well. Documentation is simply one of the those things that is too easy to put off until the last minute.

But in preparation for the release of the Movable Type 4.0 Community Solution I decided to get a jump on its documentation for a change, but only because I am planning to be in Hawaii around the time this puppy is scheduled to be released, and hell if I am going to writing docs on vacation. What I have discovered through this process is incredibly enlightening and is making me rethink my process for defining the products our engineers build.

Let's stop for a second about the documentation process we probably all follow...

When you think about it, the task of documenting a product that already exists, and the tas of documenting a product that does not exist yet, requires the writer to approach the problem from two completely different perspectives. In the former, the writer must tediously iterate over each of the screens within an application and document features someone else has already implemented. This is satisfactory I suppose because it does, at the very least, accomplish the task of documenting the product. However, this approach does nothing at all to inform the development process and to ultimately produce a better product.

Now, let's take the ladder approach, which is to say that you actually document the product before engineering has finished building it. Of course some may ask the obvious question, "well how is this different than writing a functional specification?" The answer becomes more clear if I asked you to do two things for a hypothetical feature you wanted to build:

  • Tell me what this feature will do, and how a user will interact with it.
  • Help me to understand from the beginning how I will use this feature to accomplish a task.

One approach completely detaches you from your user. Its purpose is to help document for engineering all the ins-and-outs of a feature so that technically it will work. The other approach on the other hand forces you for a second to contemplate how this feature fits into a bigger picture.

Just imagine for a second that you met one of your users at a conference and they asked you the question that I always get asked, "I love your product, but I only wish I could do this one thing." Now close your eyes and imagine how you would like to respond to them, "but you can! From the dashboard click the menu..."

In that situation, as in all situations I hope, you want your answer to be quick, clear and concise. The last thing you want is for your answer to snowball into some awkward explanation of finding some link on some page, which can only be accessed from this other page, etc.

But more interestingly, by forcing yourself to document how you wish a user would use a feature you take a more idealized perspective of that feature. For me this process helps my own internal radar to quickly detect when something is getting too complicated and naturally guides me into streamlining that feature - if only to placate my selfish desire not to spend my whole day buried in documentation hell.

Finally, finding the right time in the process to begin documentation is perhaps the trickiest part. There is no point in putting the effort into weaving a narrative around a feature that will change, instead you must start this process right before you think your engineerings are about to grasp the feature. This hopefully will ensure that your documentation can help influence their perspective and well as potentially shape the feature directly.

We should all want our documentation to be easy to understand. Just imagine if you first started by writing simple documentation and you let your product fall from that, as opposed to the other way around. One certainly seems like it will more naturally lead to the other right?

Recommended Entries

No Comments

Leave a comment

what will you say?