Consulting

How to Use Storytelling in Documentation

Wizeline believes in a multidisciplinary approach. We don't just staff engineers. Each project is a joint effort between engineers, designers, data experts, and talented technical writers. Our tech writers know the importance of great documentation, and they're sharing their tips for creating the most engaging documentation possible.

Reading a user manual is usually not as exciting as watching an episode of Stranger Things. Storytelling has been adopted by marketing and branding teams because it’s the perfect way to engage new customers. But, have you ever considered how storytelling can enrich your tech documents, and most importantly, make people want to read them?

Good storytelling requires lots of time and effort to master. And it’s the most important factor if you want your audience to connect with your writing.

How does storytelling relate to technical documentation? Does it mean that you should start writing your readme files as if you were writing a new episode for Stranger Things? No. However, there are some basic principles of storytelling that you can apply in technical writing to make your docs more engaging. The following are some storytelling concepts that, applied to technical communication, can bring a lot of benefits:

  • Defining a protagonist for your story
  • Defining a setting for your story
  • Defining a premise or reasoning behind your story
  • Defining a clear starting and ending point for your story
  • Breaking down your story in scenes

Some of these concepts may not seem very intuitive at first. Let’s dive into each one so you can start making technical documentation more engaging.

Define a protagonist (and secondary characters) for your story

All stories have a hero or main character. Your technical documents should have one too. If the user that is following your instructions has to perform their tasks using administrator access, make an administrator the hero of your story.

Different characters can be involved in the same story, but the actions they perform are different depending on the role they have. For example, let’s say your story is about the deployment of an application; if you tell this story with a developer as the hero, you would be writing a section of a Developer’s Guide. If the hero is instead an administrator, that would fit better in an Administrator’s Guide.

The actions that these characters perform are different too, even if they’re both part of the same story. For example, the developer’s mission is to make sure everything is ready to deploy and, most likely, run CLI commands to deploy changes. An administrator’s mission would be to ensure everything is ready to go to production, monitor and troubleshoot any issues in the deployment pipeline, and deploy upgrades.

Define a setting for your story

Every story needs a great location. The same applies to documentation. Before people invest time and energy on your documentation, provide them with answers to the following questions:

  • Where is the story happening? Give your readers some context. Tell them about the functions of the application, and let them know where it can be executed. Is it a mobile application? Is it a web app? What OS version do the readers need to run the software?
  • When is the story happening? Write down when you are publishing your document, and tell them when it expires. This way, your readers will know from the beginning of the document if it will still work for them.

Define a premise and reasoning behind your story

Your next step should be to write an interesting overview. This overview works as the thesis of your story, giving the reader specific information about what they are about to read in your document.

This is an opportunity to show readers that what they’re reading is important and why. Don’t just say that the Admins have to stop and restart the system when a deploy fails. Explain why they should do it, maybe even what can happen if they don’t. For example:

If the application fails to deploy with the following message: “Exception while loading the app: Timer Service not available.” It means that the Timer Service is down or that the loading time exceeded the limit. Performing the following actions solves this issue:

    • Stop the application with: ${app}/{directory}/ –stop
    • Reset the timer service: ${app}/{directory}/ –timer-reset
    • Restart the application running: ${app}/{directory}/ –start
      NOTE: Make sure to reset the timer service –even though it is not a required step and sometimes restarting the app solves the issue, the deployment may fail again if the Timer Service is still down.

If you want readers to follow you through a long process of clicking, configuring, installing, it needs to serve a worthwhile purpose.

Define a clear starting and ending point for your story

Make sure to tell your user how long the task in your document is going to take. If there are a lot of tasks required to get to one goal, divide your text into different chapters or sections. Each section should only cover one specific task, with a starting point and an ending point, just like a story.

You can have a short story about a particular incident in the life of a character, or you can have a big novel with different chapters about different things that happened to different characters. The whole novel is one story, but it is divided into different scenes or chapters that focus only on one character in a specific situation. 

The same can happen in technical documentation. If you have a big system that requires several steps to configure, make sure to divide your whole story into specific chapters, each of them with their starting and ending point. One chapter can talk about dependencies only, the second can be about the local installation, and one last chapter can talk about the deployment of the system.

If your users can easily identify the start and the end of a task it will be easier for them to follow your instructions. Take into account that sometimes people don’t have the time or the will to go through a long set of steps. Plus, if you give them a sense of accomplishment it’s a lot more likely that they want to jump to the next task later on.

Break down your story in scenes

When creating technical documentation, be clear about the tasks and their consequences. You’ll find that it is easier to follow the whole process from start to finish more easily. You will be able to follow up with the next steps in a logical sequence of events if you define who is doing what, and why.

Sometimes, people have an idea that seems solid in their heads. Then they write it down, jumping from part to another, assuming the reader will follow their same thinking process. This is not always the case.

What you believe is easy to understand can be fuzzy to others. Identifying all the steps in a task will help you realize if your documentation story is missing something. It can also help identify any areas where something could go wrong. You can add a note or warning for your readers to keep in mind when following the process.

Documenting your processes and product knowledge should spark joy. Next time you need to document, use these tips to make your writing more engaging and impactful for the people who need it most. It will not only save you time, but your readers will thank you for making their journey more exciting!

By Wizeline Tech Writers, Mario Morales and Angelo Barona
By Wizeline Tech Writers, Mario Morales and Angelo Barona

Nellie Luna

Posted by Nellie Luna on February 4, 2020