PRODUCT DESIGN

Designing better design documentation

7 ways to make it clearer and more appealing

Various documents — reports, briefs, playbooks, guidelines — usually are the way designers communicate the results of their work to peers, managers, or clients. One doesn’t simply collect all the design information in one place and call it a day. In good documentation, the how is as important as the what.

1. Start with a summary

Let’s say, you’ve made a thorough heuristic evaluation of a mobile app and found a hundred usability issues. As a result, you have a hundred-page report with screenshots and descriptions. Such serious work might have taken you a week or two.

And now imagine a person who is looking through your report for the first time, especially a non-designer. I’m pretty sure, this person will feel like the famous “stoned fox” in the picture below.

Two weeks of work— and your report rests in peace in the “Read later” folder. But by adding two slides to this already enormous document, we’ll help the audience to read less but get more.

In the picture above, the second and third slides define key issues and to-dos. The rest of the slides are rather proof than must-read information. Even if no one scrolls to the screenshots and comments, your goal will be reached because the essence of design is to drive changes, not to make people examine all the slides.

Even if you have 10 pages instead of 100, starting with a summary helps a lot. Just imagine your recipient is busy and has only five spare minutes. If they read the summary only, it’ll be a win.

As a journalist by education, I learned this principle at the university. It’s called the “inverted pyramid rule” — simply saying, putting facts descendingly in the order of their significance. Both journalism and design are utilitarian, result-oriented areas, that’s why the inverted pyramid is so useful for design documentation.

Starting with a summary works well not only for multi-slide reports but also for cloud-based information like Confluence or Notion knowledge bases. Imagine you are working on the design system documentation, and one of the pages describes textboxes; it includes mockups, interaction rules, and specs.

We, designers, tend to see the world through “design lenses” and put an emphasis on what we worked with the most. But it never hurts to introduce the interface component and then dive into details.

The same principle applies to various UX maps — journey maps, service blueprints, prioritizing matrices, and so on. For example, from a customer journey below, it’s not clear what it is about, where it’s taken from, and why one should care about it.

Let’s add background information. It’ll help the team to get the idea and use this journey map in their work easier.

And one more thing. If you send something out to people, starting with a summary is a great way to engage them. But if you present information face-to-face, it’s okay to summarize it at the end (of course, in this case, you should use storytelling to keep people interested along the way).

In a nutshell

• If you are not familiar with your audience, treat them as busy, overwhelmed people by default.
• Start with a summary if a document requires more than several minutes to comprehend.
• Keep your summary short. Let it answer the question: so what?

2. Mind the reader’s persona

Why do developers hate design guidelines? Why aren’t clients viewing UX presentations? Why don’t QA specialists look at design files? Probably because the peculiarities of their work, their needs, and their pain points were not taken into account. Team members have different focuses of attention: for someone, it’s user flows and tasks, for others, metrics and KPIs, and so on.

Your audience persona impacts both the content and its format, for instance, the structure of a document, language complexity, or the level of detail. Here is a rough example of how drastically vocabulary and content can vary for a designer and software engineer.

If you work on a design system, you are supposed to take into account multiple personas and satisfy all their needs.

Another example: a case study page can look very different depending on the audience you are targeting. In your opinion, who can be interested in the following structure and content?

This is a popular way designers share their projects with other designers. But if your case study should attract partners or clients, it’s better to focus on business impact instead of design activities and deliverables.

Another benefit of reader-centered documentation is motivating your team members to promote your ideas further — to various internal and external stakeholders. People tend to spread things they can relate to and easily explain with their own words.

Of course, I don’t advise packing bullshit into an attractive form. This technique aims to improve understanding of complex concepts and things that don’t look valuable at first glance.

In a nutshell

• Define the reader persona and adjust documentation structure, focus, format, level of detail, etc.
• People are likely to promote documentation tailored to their needs.

3. Add relative information

This method helps to show characteristics or quantities that are hard to measure. Maybe, the simplest example is the section of a user persona document where you describe high-level behavioral parameters. Needless to say, your persona should be based on UX research and be actionable — not quote common stereotypes.

So, take a look at a persona template with a story about a user’s typical day, their tasks, needs, and pain points.

It’s an already good template, but sliders make it a bit easier to scan. They are helpful when you have a set of user personas with different or even opposite mindsets or needs. For instance, when you have a primary user (mass audience) and a secondary user (internal team).

Smileys are another way to show relative data that cannot be expressed in meters, kilograms, or minutes. You might have already seen them on customer journey map templates (like in the picture below).

Various symbols — start ratings, bar charts, T-shirt sizing, 10-point scales, sliders, or emojis — have a much broader area of usage. For example, you can visualize time estimations, task complexity, perceived usability of a feature, or, let’s say, risk severity.

In a nutshell

• Show relative information to give your audience additional clues or valuable details.
• Utilize bars, stars, and smileys for displaying relative data.

4. Avoid “broken windows”

Due to this theory that originates from criminalistics, a small disorder “attracts” a bigger one. If a broken window remains unrepaired, it will soon be accompanied by obscene graffiti, a pile of construction garbage, dog poop, and a thieves’ ambush.

Although the original “broken windows” theory hasn’t been credibly proven, it’s a nice metaphor that explains something interesting about design documentation. The team’s trust in documentation is fragile. One may spend a lot of effort writing it, but inconsistencies, neglected sections, or empty pages will make people search for more reliable sources of information elsewhere.

But the most dangerous consequence is improper implementation and wasting the effort of other people. Probably the worst thing is when developers code your design by eye. Then this code is tested and returned for redesign and redevelopment. Eventually, the team and users hate this app, site, or whatever the product is.

Even if you need to share a document in the draft stage, it can look clean and be labeled accordingly. Put meaningful placeholders so that no one passes the design to production until you finalize it. Or at least team members will understand that new features are on the go.

One more aspect of the “broken windows” effect is inconsistency. If you change, add, or retire something in a document, be sure it’s updated everywhere and doesn’t contradict anything.

Moreover, practice “Lists of changes” to track different versions of designs. If something was finished and approved but changed afterward, it should be transparently stated.

Otherwise, it may cause vain attempts of the team to piece everything together and figure out which variant is correct.

Inconsistency is mainly the bug of visual design outcomes (prototypes, style guides, guidelines, wireflows), but it can happen with user research documentation as well.

In a nutshell

• When people see someone’s mistakes, they may subconsciously justify their own inaccuracy hoping no one notices.
• If something is changed in one place be sure it’s updated everywhere.
• Announce future changes and improvements with meaningful placeholders and labels.

5. Pay attention to the text

High-quality documentation is impossible without high-quality text, and I mean both wording and formatting. Good writing will help your team grasp the information easier and not bother you with obnoxious questions. Here are several things to take into account.

Vocabulary

What are your teammates used to calling different activities, deliverables, or interface components? For example, a “chart” or “graph,” a “textbox” or “text field”? Sticking to a common vocabulary helps you avoid many misunderstandings. Unlike fiction, which depicts the world vividly and excitingly, design documentation should be precise and unambiguous; that’s why synonyms aren’t welcome here.

Concision

It means using minimally required words to convey maximum meaning. You can reduce the number of words by mercilessly editing out:

• self-explanatory phrases — “On this page, you can find information…”;
• describing what one can get from a mockup or scheme — “This mockup shows a page header, footer, and five product cards…”;
• redundant words (pleonasms) — “advance warning” (all warnings happen beforehand), “future plans” (all plans are about the future), “prerecorded” (you cannot record afterward), “end result” (result already implies that it was at the end), etc.

Besides, if you notice that several points start with the same phrases, you can merge them into a list.

Lists

The beginnings of all items in a list are located one under another, making them so easy to scan and find what you need faster. Look at the picture below: in plain text, it’s much harder to see the sequence of actions or the relationship between user types.

Diagrams

If you have a bunch of interface rules starting with “if”, you are definitely considering some workflow. Of course, a designer can show this stuff by means of a prototype or mockups linked with arrows, but sometimes you don’t have time to do that. As you may notice from the example below, a text description is not the best format, although it’s widely used by requirement writers — business analysts and project managers.

I suggest organizing it in the logical map of conditions and events. Take a look at how the workflow is shown below: one can easily follow the success scenario and see potential errors.

In a nutshell

• Agree on the terminology with your team and use it consistently.
• Edit out redundant words.
• Create lists and diagrams when it makes sense.

6. Opt for cloud collaborative tools

Every document is created to be seen, read, and understood. Otherwise, there is no reason for creating one. You might be surprised by how many companies still have prehistoric email clients limiting attachments to a megabyte; how many pieces of software and fonts are missing on other computers; how many teammates don’t have accounts in tools you consider to be “standard.”

I guess designers can either utilize basic tools or — preferably — build as autonomous and flexible an environment as possible. Fortunately, we live in the age of almost hardware-independent cloud tools and online collaboration (Dropbox, Google Drive, Invision, Trello, Figma, Google Docs, Dropbox Paper, Confluence, etc.).

However, old good files have a couple of benefits, for instance, they work when there is no internet and give a feeling of owning something “tangible.” Universal formats like PDF are good for archiving old designs, whereas links to online resources might expire or web services can be closed down. I can not open some of my very old files because relevant tools don’t exist anymore.

If the only available option is to prepare a PDF or something similar, be sure it’s lightweight and compatible: has no dumb layers, overkill effects, and lots of non-cropped and non-compressed bitmaps.

In a nutshell

• If you don’t know for sure who your audience is, perceive them as non-technical folks with low-performance equipment.
• For long projects, especially with design systems and distributed teams, cloud-based documentation is indispensable.
• Take advantage of standalone files as an archive for finished work.

7. Add emotion

Good documentation provides information and serves its purpose, but can it also inspire people and make them feel better? I believe that additional fun elements increase documentation adoption and make it more exciting. Of course, they can’t replace clarity, concision, and accuracy — only amplify everything that’s already there.

Fun and memes

What makes you and your team roll on the floor laughing? Is there anything funny only the people involved in the project will get? Then make it an easter egg somewhere in a document. Of course, it should be elegant and not confuse readers.

Once I decided to add fun and usefulness, and it worked. Firstly, my colleagues smiled. Secondly, they were redirected to alternative stuff, which could substitute what they were initially searching for. It was the time when Travolta’s meme had just appeared, so it was funny.

Stylization

Is there a symbol, mascot, or positive association connected with your project, product, to team? Then why not include it in a slide deck, guidelines, or research report? A couple of ideas of what you can use depending on the topic:

• taxi service — car emoji as bullet points;
• dog food delivery— bar charts in the shape of bones;
• art marketplace — classical art memes on the slides.

Storytelling and personification

We are humans and expect good stories even in business. That’s why it’s so important to speak about general things in a specific, personified manner. Since designers are often portrayed as the guardians of team empathy, storytelling is often on us.

Team photos

Another powerful technique is to use real team photos instead of stock ones. Of course, you should remember to take such pictures during team activities: brainstorming, UX mapping, planning, etc. If you collaborate remotely, no problem — take a screenshot. This method helps to:

• support empathy and a positive attitude to the project;
• remind everyone that this deliverable (presentation, guideline, or report) is a result of joint efforts and analyzing the problem from different sides.

Today you facilitate a workshop, and the next day you show them a presentation with their photos. Every time I do that, people smile and are proud of contributing to the project. Photos aren’t a magic wand, but they make presentations more appealing.

In a nutshell

• Use emotional effects like storytelling, memes, or stylization to increase the impact of documentation.
• Insert real team photos instead of stock ones to presentations even if they are of lower quality.

• If you found this article useful, feel free to buy me a coffee ☕
• Here is a publication with all my design articles on Medium.
• Let’s connect on Linkedin and Twitter.
• Drop me a note if you want me to present this or another design-related topic at a conference or meetup.
• Bored by “how-to” design articles? Check my other blog where I talk about overlooked architecture.