A theoretical response would be yes. But in practice, in the real world it always turns out to be no.

The aim of documentation is no longer to describe everything, simply because it can’t. No one will invest in this anymore. It has to be an added value to the software proposal. If it’s not, then it is probably doing the wrong thing.

Objectives of documentation have to be defined as a value proposal by product managers or product owners:

  • I want to cut training costs.
  • I want less and less people calling my support teams for basic help.
  • I want users to adhere to the way I tailored their technical procedures in my software.
  • I need to explain the way my software steps outside the beaten track.
  • I want to onboard my users easily.

Should I describe everything?

Once again the answer is no.

If you have to paraphrase what is seen in the user interface or describe how to circumvent, go back and have a look at ergonomics at interface terminology. Technical writers have a serious role to play in GUI interface design. More often than not, software editors totally ignore this key design phase.

Most elements of software GUI should be self explanatory. Then documentation is written as an added value to achieve procedural clarity.

Key in-situ contextual documentation should aim at describing what can not be done in the GUI for ergonomic reasons and adding the blocks of information that explain the objectives, procedural position and key concepts needed for understanding.

Additional information is detached from the software GUI (and should be linked to this where applicable). Choose what is actually necessary by putting yourself in the place of the user – I’m at this given point in the software – what do I really need to pay attention to ? What does the editor need to attract attention to? For instance, avoid future frustration, procedural errors, or improve a learning curve.

Validation should take an editorial approach. This means that from the outset, the entire project is managed as an editorial project, with specific aims.

Self explanatory GUI

Achieving this is often a question of proper design and third party testing. By third party we mean first of all not a programmer.

Older software tends to talk to initiates, while a new tendency is to overkill. A balance between the two is preferable, especially when addressing a known sectorial user base.

How to avoid having to write everything?

Aim at writing documentation that covers a predefined percentage of software procedures and GUI.

Then use feedback from users through support teams for adding additional information. This will enhance user satisfaction in a product life-cycle and show both reactivity and attention to user experience.

Just as we talk about onboarding users, your product users can largely contribute to enhance an information system around your software. This is where the paradigm changes. Users generally know what they want to achieve and can contribute to information around a product is the proper mechanism is provided through help desk systems or documentation systems.

Capturing user experience enhances the pertinence of information delivered with a product.

New tendencies will be moving towards user support knowledge systems instead of documentation only and community building to enrich a user-client base.

Who should re-read and validate before delivery?

Well, it almost goes without saying, not the author.

Documentation writing is an editorial process and should be managed as such by a product owner.

Validation in simple structures can be done by a co-author. In larger structures it can be done by a product owner.

The key to enabling this is establishing clear editorial guidelines and objectives from the outset.