Tuesday, November 25, 2008

Remember the (STC) Alamo

Just over a week ago I attended what was simply the most open and stimulating regional STC event I have ever been to.

The Central Texas STC Fall Seminar, was organized jointly between the Austin and San Antonio chapters of the industry group and held at the excellent Hotel Valencia on San Antonio’s famed Riverwalk. (Home to many fine restaurants - including the one where we had lunch.)

But it wasn’t the setting that made it memorable – it was the participation.

In my experience a lot of these regional get-togethers end up in features and functions comparisons of tools, minutiae of the job, or arcane technical discussions about standards that only a minority of people use. Not so in this case.

The discussions ranged from using emerging new technologies, Web2.0 tools,, wikis, social networks, to how to develop and recognize metrics, to how to make sure that the documentation process is heard and accounted for in a Agile Development driven world.

But underscoring all the talk of technology was the realization that technologies will come and go, and the most important skill to develop was the ability to learn about new things, and communicate that in an empathic way.

There were several people who were attending their first STC event and they, along with everyone else, left with the impression that this is an exciting time to be in the corporate publishing world.

Thursday, November 20, 2008

Is there a case for "Just Enough" Documentation?

A couple of what at first glance appear to be disparate unconnected posts picked up by my Twitter feed over the last few days got me thinking about just what we should include when we produce product documentation.

On her Twitter feed consultant Sarah O’Keefe posted the following quick observation: "Inbox Zero once again. Today's lesson: When you ignore stuff, much of it becomes irrelevant.” This is a productivity, time management technique that I have used for years. One of the first things I was taught at management college was that never keep anything on the “to-do” list longer than 30 days. If you haven’t got around to it in 30 days and no-one’s complained it probably wasn’t that important. Delete it, and if it is important someone will remind you. Like Sarah I also apply a similar philosophy (but not time scale) to the contents of my Inbox.

Then today, Alyssa Fox from NetIQ posted a quick note on her Twitter feed that “SE just found a bug in our doc that's been in there 5+ years. Obviously no one ever reads that section,” to which I responded “If no-one's read that doc in 5 years - is it really necessary to have it there at all? Why write and maintain something no-one uses?”

Over lunch I began to realize that the two thoughts had a definite connection. Traditionally we tend to document every feature and function of a product. We expend many hours describing how something works. Yet how much of what we produce is ever read or used?

Most users are only interested in learning how to set something up and start using it in the shortest possible time. Secondly they want to get answers to very basic “how do I” type questions. With this in mind I’ve recently been conducting an ad-hoc, and very unscientific, straw poll about which documents (print, on-line help etc.) that people are most likely to use. The result is very clear that the thicker and more voluminous the documentation appears, the less likely people are to use it.

So going back to the “ignore it and it becomes irrelevant” thought. If sections of documentation are never read, accessed or used, are they irrelevant? While the engineers and designers may not think so, it seems clear that the users do.

Is there a case for “Just Enough” documentation.

At WebWorks.com we recently went through a process of rewriting our complete documentation set. At least that was the original goal. Yet when we compared the old documentation set against the project time frame we realized that we would have to make a decision about what was necessary and what was just “nice to have.” The project was lead by one of our MVP users who could give us the user perspective on what was needed and what could be left out.

But how will we know if we’ve made the right choices?

We posted the new documentation set online as a wiki. We have enabled comments so users can directly tell us if there’s something we missed. If we need to, we can create a new piece of documentation and publish it quickly. But perhaps best of all we can now track which document pages are visited and more importantly which aren’t.

It may take a few iterations but we will be able to fine tune the documentation to provide just the information that our users need and use; allowing us to focus effort away from maintaining “irrelevant” dead pages to making sure that he have “just enough” documentation to make our users successful.

[This entry is cross-posted to my WebWorks.com blog]