Software editors have less and less resources to create user-oriented documentation

In the evolution of user-oriented documentation:

Cost reductions have led to cutting back on the effort to produce user-oriented documentation.

Documentation has proven more often than not hard to maintain.

The return on investment and the true added value are unclear to most (small) editors.

Mobilizing technical writers has been a problem for medium to small size editors.

On the other side of the picture, most users have done without. In our experiences, it does not mean they can live without help in all cases. Often, absence of documentation is compensated by more user support requests and repeated tickets.

This is a paradox: it’s probably needed, but rarely properly supplied, and in this case, frustration is built up on both sides – the users and the editor.

So, how can we get over or resolve this paradox. Let’s explore a few elements of response in order to see if we can bring back value into the documentation and identify a clear more proximate ROI.

Does software always need comprehensive documentation?

No.
Comprehensive is long gone. First of all, what was this ? Typically this was very open to interpretation and chiefly concerned a client – supplier relationship where the impression of a first level of ROI is volume. Furthermore, covering each and every aspect of software in documentation is not necessarily meaningful.

What should be essentiel then?

Our own response is to make documentation to be as contextual as possible

Does documentation have to be outsourced?

There are advantages and disadvantages to outsourcing. It’s a strategical decision. If you need to add technical writers for your documentation, we’d recommend you add them to your team (even on a contractual basis).

It’s pushing off responsability to outsource your documentation. The entire editorial strategy definition phase of documentation is the reponsability of a product owner or manager. During building, coordination between experts, programmers and writers is an on-going process. Today we manage this by iterative scrums. Writers can be outside if they have easy access.

Does documentation have to be written by specialized technical writers?

Not all of it. Getting other people involved is essential – support teams, product owners/managers, even programmers or team leads. Documentation isn’t abtract and technical writers can’t work alone, they’re part of a matrix. Whether you need them or not is a question of final consistency, style and probably rapidity.

Does the writing team have to be in-house?

Our preference is yes. Software production cycle are shorter in general. Agile methods contribute to this. In-house no longer means hiring people. So yes, getting good integration between support, development and writers, especially since some of the documentation produced is destined for the support teams, is at least an objective if not obligatory.

How can you deliver the essentials?

Concentrate on in-situ contextual needs. Identify the parts of the GUI that reuse this.

Identify how added value is built by documenting faqs, short procedures (how-to’s).

Explain concepts.

The essential is the strict minimum, not a comprehensive corpus. Then test the documentation and proceed by iteration until you have a good adequation by identified user needs and content. Then stop and wait for feedback.