The era of big doc is over

Documents in an information proposal are counter productive

At TECH’advantage we are software editors in the oil and gas industry. When we talk about doc in this article we mean user-oriented documentation. This article is based on our experience over several decades are orientations driven in conjunction with our clients as they move to information infrastructures oriented towards Industry 4.0. The article explores what we need to do now and where we have to go to a complete transformation of information production methods, delivery and experience.

Why is the era of big doc over?

Several factors contribute:

  • Economics: software products can no longer be produced with huge documentation projects (unless you an airline manufacturer maybe),
  • Evolution of reading patterns: the way people read and the time they spend reading in the workplace has changed a lot with the use of the internet. Availability and concentration spans have greatly shortened —we’ll spend time on emails because we have no choice, but we prefer not going beyond a page in reading.
  • The need is immediate: it always has in reality. Before we had little choice but to wait. Today we expect immediate answers. Documentation has its own production cycle and often does not deliver when expected. Readers will go for the next best answer whatever the source. This contributes to degrading the image of documentation and builds up user frustration.
  • Big doc doesn’t cover current expectations: information in huge volumes makes what is momentarily pertinent hard to find. It requires searching and indexing, which typically indicates we have not produced the information the way it is expected, or we buried it.

What direction do we need to take?

The direction we need to take involves what we product, how we work, how we deliver and reviewing what we think our role is.

User experience(s) at the core

The fundamental next step involves getting back to dealing with user requirements by looking at the matrix of user experiences and the different persona in which we can summarize them.

First, let’s not confuse experience and user experience. The first is know-how, the second is his experiences of course.

User experiences are very different depending on the field of application and the complexity of the product. User experiences need to be catered for and not just a linear vision of their experience in products — a user can have different experiences and different persona, especially in complex software.

To cater properly for user experience do we have to deal with persona? Yes.

Have a look at this article for a deeper vision on personas and how we can deal with them: Personas as a means for mapping user experience for information delivery.

To make it short, in our case, producing content around software, user personas can be considered being beginner, literate, proficient or expert. If we deal with these cases we will cover a broad range of sufficiently different fields of experience. In simple products, this is more or less a linear evolution from one to the next. In complex products, a user can be an expert in a field and a beginner in another.

It is extremely important to map out content to cater for these different levels or personas if we move in that direction.

Delivery vectors decided before content

Documentation is a dead end. Delivery has to adapt to the needs of a content matrix.The overall goal is to take users on a long journey: onboarding – starter to proficiency – making them experts.

Several vectors need to be looked at closely:

  • in-line context sensitive content,
  • onboarding oriented content for starting with the product or even new options.
  • easy to grasp procedures with clear steps.
  • response to questions imagined by working on personas – faqs designed with support.
  • short training supported by videos.
  • business-oriented materials for expert use – getting added value out of the software.

Build from the ground up

This is already dealt with in another post: Writing software documentation from the ground up.

What’s important is not writing the content all at once. Build it in stages. Start with priorities defined in a content strategy.

Get feedback asap. This will orient content with an eye on what the software users need.

Keep it simple

Try working on content that is just barely good enough. Write with an eye on where it is being used and by who. Appl minimalist techniques.

Write only the essentials and trust the community to come back with questions.

Plan reading as being staged information acquisition, not all at once. Don’t mix-up concepts, faqs and processes. Instead provide access through links.

Avoid screen captures when you can.

Create content that isn’t just text

Use all the forms of multimedia that are adapted. This does not mean producing pdf formats that require a download and offline reading.

Use schematics, animations, short videos, embedded guides, slideshares that are short. Most of these can be wrapped up to fit other needs too.

Delivery

Delivery of each content format has to be in the right place.

The first place is in sit, inside the software with the correct granularity, and context related. Further reading is planned as steps on a track, a journey. Encourage short absorption instead of long content.

Portals are the future for an overview of information content if they are properly designed for access; taxonomy has to be used to parallel content navigation. feed-back has to be designed into them.

Encourage involvement and capture back

Portals are key to encouraging the software user base to get involved and contribute. This allows you to:

  • measure satisfaction and pertinence,
  • map out future needs,
  • open a track to self-help,
  • improve know-how without having to write it all.
  • identify expert contributors that you can get involved.

Doing this is the first step to know-how capture, practice improvement; In turn, this will alleviate support and make the more useful to improving the user experience by improving skills.

Throw out the garbage

Documentation is dead – it was static. It’s cost made us wary of removing anything.

We’re in a rapid cycle of information delivery. Quality has to be achieved faster than before for a community that may even be hostile to reading, especially if it’s long and tedious.

Analytics should help us determine what is used on not. Feedback should help us improve. Then, when this is done, throw out what isn’t used, re-write what need to be. Tune it step by step.

Delivery more than what is useful is counter productive.

Managing all this is part of a content strategy

All of these considerations are what we see as part of a content strategy for user-oriented information around software products.

This is already dealt with in: