Home

Documentation: Serving the Application Lifecycle

14.09.22

by Luca Vettor

Delivering a valuable experience to the audiences of technical documentation is paramount, as they need fast information to complete their tasks quickly. The way to reach such a result is by delivering as little documentation as possible, with just the most relevant information, and within a coherent structure

14.09.22

by Luca Vettor

Delivering a valuable experience to the audiences of technical documentation is paramount, as they need fast information to complete their tasks quickly. The way to reach such a result is by delivering as little documentation as possible, with just the most relevant information, and within a coherent structure

Ideally, any application, service, or platform should deliver features so close to the users' needs that they require no documentation to start using it. 

However, real life is different, as many of us likely know.

Nevertheless, users tend to perceive reading documentation as additional work they would rather avoid – and they’re right to think this. From this standpoint, any single row of documentation reflects a failure in simplifying the application enough to make that row unnecessary.

In other words, a big part of effective documentation is to provide a deliverable that users don’t desire but do need. So, as technical writers, we have to write as little as possible and document what matters. Accordingly, this article suggests an approach to making documentation effective and purposeful.

The documentation's structure is pivotal

Defining “content that matters” depends on the specific user needs, and is the outcome of research and interviews with the subject matter experts (SMEs).

So, which guidelines can help write adequate documentation regardless of the content?

Well, the application lifecycle provides one answer. Any application, service, or platform needs these companion documents:

  • Release Notes. It answers the question: "What's new in version X?"
  • Changelog. It answers the question: "How do I upgrade to version X?"
  • User's Guide. It answers the question: "How does version X work?"

Each document relates to a specific version X, the critical information that locates the documentation in time – and this applies to any application, service, or platform.

The same is true for questions that each document answers. In fact, on release of version X of the application, the users need to know:

  • What's new?
  • How do I upgrade?
  • How does it work?

Regardless of how and where these pieces of information are delivered, product users know they need them.

01

Join us

Principal Software Engineer - Video Experiences

Apply

Documentation that matters delivers value to the product’s users

As technical writers, our mission is to make the users' life simple. The first step toward simplicity is consistency in building the documentation as a triple:

  • Release Notes
  • Changelog
  • User's guide

The next step is to structure each piece of documentation in a way that makes it easy for users to discover "What's here for me?"

Release notes: What's here for me?

New benefits.

It's about copywriting.

The content of the release notes justifies the new release;  it explains, in persuasive terms, why users should buy the latest version of the application.

The release notes' audience is twofold.

On one side, it explicitly addresses the users' need to know what's new and why it’s so fantastic.

On the other side, it caters to buyers for which the content of the release notes is a piece of crucial information to decide whether paying for the new version is worth it.

02

Join us

Software Architect - Sport Experiences

Apply

Changelog: What's here for me?

Upgrade procedures.

Adopting a new version of an application always implies changes to the systems that include that application. The changelog aims to make those changes smooth.

Due to its nature, technical people are the audience of the changelogs, and technology is its language and style.

User's Guide: What's here for me?

Instruction manual.

Last but not least, once release notes convince clients to buy the new version of the application and the upgrade is in place, a detailed instruction manual has to help users benefit from it.

Users are busy and want to do their job as quickly as possible; this is why, as technical writers, we have to write as little as possible and document only what matters. This guidance is applicable to the release notes and changelog too, but for instruction manuals it’s even more relevant.

There is no universal truth about how long and complex an instruction manual should be because it strongly depends on the application's business. Nevertheless, technical writers must answer a crucial question before writing an instruction manual: "How much time are users willing to invest in learning how best to use the application?"

Fail to answer that question correctly, and you’ll probably have highly frustrated users.

03

Join us

Associate iOS Developer - Video Experiences

Apply

Conclusions

Is the recipe in this article the only possible one? Definitely not.  Yet, it is a recipe that is made up of questions rather than of rigid prescriptions, so it can easily be adapted to any application lifecycle.

The only truth to never forget is:  Know what your audience needs and deliver on those needs.

04

Join us

Engineering & Technology open positions

Explore roles