User focus - how far do we go?

Happy 2010!

I came down pretty heavily on the side of user focused documentation in my last post, with talk of "enacting use environments" as a way of deciding what documents to provide, and what content to put in them.

Briefly, to produce a manageable documentation set, we need to identify a set of users with similar goals and work with them through some kind of dialogue so that we and they inhabit the same use environment.

This is manageable enough when the only participants in the use environment are the system and the user, but it becomes a lot harder when more than two entities are involved.

A hypothetical company (let's call it Fictive, Inc.) provides two software products for servers, "Base" and "Do Stuff". "Do Stuff" needs "Base" to work, so when you install "Do Stuff", "Base" gets installed on the same server automatically. "Base" provides a Web interface to "Do Stuff", which could equally be applied to any other product built on "Base"; "Do Stuff" just defines a bunch of functions with parameters.

Today, I am the technical author/content strategist/information architect/knowledge manager* for Fictive. In my drive for user focused documentation, I have been treating the Fictive software as a single unit, because that's how it's experienced. To do some stuff, the user needs to know both the function names and the parameters ("Do Stuff") and the way to encode them over the Web ("Base"), so I combine these into structured use cases with a bunch of examples of how to do each thing.

Now, Fictive make the decision to promote "Base" and "Do Stuff" as independent products, so my user based documentation for "Do Stuff" suddenly balloons to include all the flavours of "Base" we want to support. But if I split "Base" from "Do Stuff" in the documentation, I force the user to learn about the interface: functions will have to go in one document, and how to call them in a different document. Concrete examples become impossible.

Within Fictive, we can spot this and it's clear that it would also cause support headaches, so we end up recommending a particular version of "Base" for our release of "Do Stuff", and the server documentation can remain together, and nicely user-focused.

Unfortunately this isn't the end of it. Fictive's server isn't actually what our customer cares about. All the data that goes into "Do Stuff" comes out of a separate system made by a sister company of ours (say, Ficsis GmbH.) Ficsis has written their own UI for their product, which ultimately controls what stuff is done. The customer needs to know how to work that UI so that the right answers come out of "Do Stuff". Is that our problem, or Ficsis's? What ends up happening is the user gets burdened with learning about another interface, to inhabit two use environments simultaneously-- with Ficsis and Fictive pulling them in two directions at once.

It's in fact worse than this: the user really cares about an entire system, which sits in a rack and has within it servers from four or five different vendors. Each vendor has its own documentation team, who are busy enacting use environments, trying to mould the user to fit their convenient model. And it's because of this that systems integrators have jobs. But the problems started much earlier, in fact back when we defined an interface between "Base" and "Do Stuff".

So what's the answer? I think I made a mistake right at the beginning. The use environment of the "Base" and "Do Stuff" documentation isn't the customer at all -- it's the systems integrator. They are the only people who know what the final user will want to do, and how they will be able to achieve it.

Now I made this mistake because it happens that Fictive often does the systems integration work itself, and that they are too small to have a dedicated documentation team for each project, so the core documentation has to serve two purposes. But that is a compromise Fictive have had to make as a company, and however much it may annoy me that I have to move away from user focus, I have to realise that my idea of "user focus" didn't see the big picture in the first place.

* I really must pick a job title this year.