At TECH’advantage, we are software editors in the oil and gas industry.
When we talk about Big Doc in this article we mean user-oriented documentation.

This article is based on our experience over several decades. Our 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.

Rethinking the Big Doc

In our view, long-form documentation, with a few exceptions, is going out of style. But it’s more than style that contributes to our thinking at edc. The Big Doc is necessarily at the end of its lifespan for several reasons:

• Economics: software products can no longer be produced with huge documentation projects (unless you’re 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 are shorter —we’ll spend time on emails because we have no choice, but we prefer not going beyond one page of reading
• The need is immediate: in reality, it always has been. 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 user frustration
• Big doc doesn’t cover current expectations: information in huge volumes makes what is pertinent momentarily difficult 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 produce, how we work, how we deliver, and reviewing our roles, or what we previously thought our roles to be.

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 personas in which we can summarize them.

First, let’s not confuse experience and user experience. The first is know-how; the second is the user’s 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 personas, especially in complex software.

To cater properly to user experience, do we need 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 as 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 one 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 must 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 examined 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

How can we create content users will actually use?

So, if the Big Doc is dead, what do we do instead? We create content that meets all of the criteria of today’s users.

Build from the ground up

Building from the ground up summarizes the documentation approach we advise:

• Start with basic in-situ documentation and attach it to the software interface
• If possible, contextualize this information
• Then write the other forms of documentation as needed.

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 whom. Apply 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 unless they contribute new or necessary information.

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, and slideshares that are short. Most of these can be wrapped up to fit other needs too.

Delivery in the right place

Each content format must be delivered where the user needs it.

The first place is in situ – 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. Customer feedback should be designed into these information portals.

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 it more useful to improving the user experience by improving skills.

Throw out the garbage

Documentation is dead – it was static. Its 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 or not. Feedback should help us improve content. Then, when this is done, throw out what isn’t used, re-write what needs to be. Tune it step by step.

Delivering more than what is useful is counterproductive.

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.