Lana Brindley - More than words: Reviewing and updating your information architecture

This is a summary of a talk given at Write the Docs Prague 2021.

Lana is an Australian tech writer joining us from the Gold Coast. She’s a bit of a gym junkie and owns a coffee machine that is smarter than her. 

She’s moved to a new development with lots of adverts. The developers of the properties rely on thinking that making an architect design your home makes it a bit fancier, but most apartments are just tiny boxes stacked on top of each other. 

An architect is the person who designs the building. They don’t buy materials or do anything to do with electric and plumbing. They are purely responsible for the design. Can you have a home that hasn’t had an architect? 

One of her guilty pleasures is to browse bad real estate photos. Many of them haven’t had the benefit of an architect. The thing that’s gone wrong is not the construction or the furniture - it’s the design. 

The words you design are like kitchen drawers. They need to be designed in a way that can actually be used. 

1. Map what you have

Most technical writers already have something written down. You need to make a critical assessment of what you already have. 

You need to create a content map. If you have a few hundred pages, then you can create a table in a document. If you have a giant wiki to categorize, start with a spreadsheet. 

2. Content types

Lana says her favorite is the DITA model. There are three different content types: concepts, tasks, and references. 

• Concepts describe how and why something works. 

• Tasks give specific instructions on how to get something done. 

• References are structured information or specifications. 

Most of her content was mixed, with concepts interwoven with tasks - which is a massive red flag. 

When it’s all mixed up, it becomes difficult for everyone. 

3. It’s all about the readers

According to Lana, you should think hard about who is reading your docs. Users use the software and readers read documentation - sometimes the two overlap! Your readers are not always your users. Depending on your product, sales and support staff may use your docs more than end users do. 

In the open source world, people read your docs to see if they want to be involved in the community, use your tool for their own project, or fork your product for their own use. 

Why do people read docs? It’s usually because they want to achieve something. We need to work out what problem the reader is trying to solve. 

It’s better if you can go out and find out who your readers are for real. Try and get in contact with them any way you can, perhaps a series of 1-1 interviews. If you’re in a larger corporate environment, start with sales staff. 

There are many benefits of asking. You’ll get direct feedback on the docs and understand the pain points. In the longer term, it lets people know you care about docs and builds community engagement. 

It’s important to understand what readers actually want rather than what they might want. Readers said they wanted more explanations of how things work, rather than more step-by-step instructions. What readers want is not always what they say they want. 

4. User/task analysis

Lana recommends validating what you probably already have in your head. You need to know who your readers are and the top things that readers want to achieve. 

Think of beginner, intermediate, and expert users. They will probably be interested in different parts of your product and need different types of help from your docs. 

5. Organization & navigation

We need to see if the way things are organized now matches what our readers want. Humans have a tendency to sort things into hierarchies, but they don’t work very well for when you need to find something. 

It’s a bit like moving house. You pick up one thing, put it somewhere reasonable, and spend days and days trying to find it again. 

Putting things in a reasonable place is a very different skill and uses a different part of your brain to find things. 

Are users coming to you directly? Are they typing docs.yourcompany.com into search? When they reach your page, what page are they landing on? Where do they go next? Do they search for something else on your site?

Several methods to search the docs relied on readers already knowing what they wanted to search for. They had a lot of new readers and a lot of getting started tutorials. They needed to develop a way for people to navigate that would lead them to content they didn’t know they needed. 

Often readers know what they want to achieve, but they don’t know the words to describe that thing. 

6. You and your thinking brain

It’s time to write all your brilliant ideas down, even if they’re incredibly unrealistic. 

This step is an implementation plan, where we decide what is actually feasible and a suitable time frame. You need buy-in from management to succeed in this step. 

Work out what resources you have in terms of people, time and money. If you don’t have much time, you’ll need more people to do the work, and money to cover outsourcing the work. 

What is the Minimum Viable Product? This could be a small reorganization of existing content, or adding site search. 

You get to pick the things you can do on your list within the constraints. 

7. Do it! Go on. 

You have to go ahead and do the work. 

It’s important to measure your success. If you’ve done your planning properly, you’ll have a good starting point to measure how things have changed. One measure of success could be improving dwell time on each page, and for this you need to know what your dwell time was before you implemented your changes. 

Final remarks

Lana assures us that design architecture is more art than science. The most important thing you can do is listen to what your readers are telling you. 

And that’s good advice for anyone. Always keep your readers front of mind when reviewing and updating your information architecture. 

Listen to the full talk here.