Guides, FAQs, and documents: the job of a technical writer
The experience of the Digital Transformation Team: changing the language of the public administration, one sentence at a time
We all need guides
We are constantly looking for information online: from the apple pie recipe to the latest JavaScript library, there's always something that we don't know or some information that is missing.
This is a very familiar situation: every time we have a problem, our first idea is to go online and ask a search engine. We find a few, carefully selected words and we enter them in the search box. If everything goes well, we find what we were looking for, we follow the steps described in the guide and we put the cake in the oven (or, we publish our shiny new website.)
Sometimes, however, things don't go as planned, and the guide we find is not that clear. We lose time and energy, we get angry, and we go back to our life in a state of frustration. Plus, we didn't get what we wanted!
Enter the technical writer
Recently, we started a technical writing activity within Docs Italia, the new platform for Italy's technical and administrative documents. Docs Italia is a project developed by the Digital Transformation Team. Technical writers sit halfway between what we want to achieve and our happiness. Their job is to understand users' needs and to write guides that will help them in their tasks.
Technical writers typically create user manuals for physical devices and machines, software how-tos and API documentation. (No, the apple pie recipe is not one of the duties of a technical writer.)
The documents produced by technical writers generally fall into two categories.
- Technical docs: technicians and engineers are the intended audience. For example, a municipality wants to adopt the digital identity system and hires a software house to do that. They will need a guide that explains, step by step, how to implement the software. In this case, we use a technical language. The main effort is, quoting designer John Maeda's words, “subtracting the obvious and adding the meaningful”. In other words, removing everything that doesn't serve a purpose, leaving only those elements that will help the users reach their goals without distractions, without "noise".
- Guides for a product: they describe the product and how it works to the users and to the customer service. For example, think of the FAQs section of a website, where users can find answers to their problems. In this case, the aim is to interpret and foresee how people will use the product, without worrying too much about the technical details. You need to create trust between yourself and the user. And the key way to achieve this is through simplicity. Quoting Maeda again: “In simplicity we trust.”
In reality, having the users' needs in mind, a "guide" can often become a table, a diagram, a picture or any kind of content that might serve the purpose well. Therefore, a technical writer's job is often closer to that of a content designer, than to a pure writer. Technical writers are, in fact, the bridge between technology and the users. For this reason, they must have:
- technical skills: they must be able to understand technology to a deep level before describing it;
- design skills: in particular, they must have content design and user research skills, to be able to communicate effectively their ideas.
Simplify and imagine
Two words best describe what technical writers do: simplify and imagine.
You need to simplify when you want to make a topic accessible. You need to remove all the barriers that might prevent someone from understanding the text.
Long sentences and difficult words are the first hurdle. In this case, plain language, that is using a simple and clear language, is helpful. There are some simple rules regarding this in the Guidelines for the design of public services. In these weeks, we are working on improving this chapter, adding more useful information and tools.
Technical terms and jargon are the second problem. These words are often difficult to understand by non-technical people. In this case, you might have to use these terms anyway if you want to be precise. Their meaning, however, should be clearly explained in a glossary included in the document.
Simplifying doesn’t mean dumbing down, but opening up, paraphrasing the famous motto of GOV.UK.
Imagination, on the other hand, helps to understand what users want, need, and seek. It means imagining their actions and their journeys, planning content in a way that makes their lives easier.
Simplifying and imagining are strongly connected: if you put yourself in the users' shoes, you will imagine what they feel and think in front of a text. If you're able to imagine what makes them frustrated, for example, you can think of possible ways to solve this.
Imagination is not enough
Imagination is important, but is not enough. First of all, technical writers need to know how to write —and how people read— texts online: how to use links, how SEO works, and how to create effective titles. These skills are discussed in a section of Designers Italia devoted to content.
Second, technical writers need to have objective data about the users. They need to participate in user research activities, and in some cases they need to be able to carry user research directly. They must have the skills to analyse all available data about the users, in order to improve the documents they write.
For example, Docs Italia uses the web analytics tool Piwik/Matomo. This allows us to know how many people read a document, how and for how long. It's important to know which words they use to search for the documents online, and to compare them with those inside the text: in this way, you can match the content with the users' needs.
Usability tests are another useful tool. They help understand how a user interacts with the product (a web page in this case), in order to perform a specific task. The information that can be obtained from these experiments is fundamental in understanding the weak points of a guide and to find possible ways to improve it.
The revolution has started
Docs Italia is the playground where we experiment with these ideas, day after day. Our goal is to change the language of the public administration, starting from administrative documents and project guides.
Docs Italia's revolution is about focussing on the citizens, starting from a language that is close to them. And technical writers are precisely the tool for this change.
