To develop effective documentation for users, the writing team should understand the experience of the user. This is harder than it sounds. Writers, like anyone who works in software, build up a tolerance for the vagaries of software was it moves through development.

Think of the old days, when you would have to orient the rabbit-ears on your TV set and hold your arm out to get the UHF channel that had the ball game. At some point, you stop thinking this is weird. (For you kids who don't understand this, well, download some music or something.)

Re-visiting this user-centric model, requires the writer to identify when s/he stops seeing the idiosyncrasies of beta software. For instance, oftentimes, you have to perform special weird instructions during the installation of a product that is still in beta. But that's not going to be the user experience. Well, it better not be!

So writers and editors go to the trouble of re-focusing periodically to get a more user-centric viewpoint. They re-organize the Table of Contents. Or, go 'off-site' to do some new fangled training exercise. These, and other ways of seeing the user experience, are quite valuable though they often seem a little odd at first. And like a lot of things in corporate life, the exercises seem like an unnecessary re-hash of similar exercise of the past.

Orienting the documentation back towards the user is often a corrective measure. Why is it necessary? It's necessary because the people creating the software, the product team, are the primary source for the material. After all, they just made the thing. They are the only experts. And as the writer moves along in the application life cycle, with the application, s/he gets sucked into the orientation of the developers, testers, and other fine people that make software.

Posters

Our team just started one of theses corrective exercises. We got the idea from another writing team of a different product. We are trying to create posters that describe the complicated process of using Team System to develop software. I think the goal of the posters is noble, i.e. re-orienting the documentation and the writer to the user-centric viewpoint.

Some people are really good at seeing this kind of grand vision. Others do not come to it easily. Some are good at creating it. Teams usually have a mix of people and skills. In fact, as long as teams effectively co-operate, avoid becoming territorial, and head towards a common goal, the variety of ways of thinking can help produce better results.

It's hard to stop thinking about old features and new features when the product team's reason-for-being is that singular pursuit. But that's what they should be doing. They need to make sure that all cases are considered not just the primary ones. And while users want reliable and high quality software, most experience the primary scenarios and not all the odd ones at the margins.

The user's actual view does not contain features that don't exist. Imagine I handed you a cork screw but you'd never experienced wine. Even if I explained how to use it (the corkscrew not the wine), you'd still be scratching your head. A picture (maybe from a poster) might be a good way to provide the user with a way to fit-in new feature knowledge with the existing user-centric models that already exist in their heads.

For me, the poster exercise hasn't yet coalesced, but sometimes that takes time. I suppose it's possible that poster exercise just won't work for us. I think the other team said that it actually took months to gel so we are just starting out. However, it has reminded me that our job, providing help to users when their understanding is breached, is more user-centric and less product-centric. But it's harder than it sounds.