Why do they ignore my awesome design documentation?

Creating a live environment, not a cemetery of ideas

These are the best guidelines ever! Oh, wait, no one watching?

In 2017 I wrote several tips on better design documentation. While all those tips still make sense, I realized there is a more vital thing — and it’s not what you may think. It often happens that the stuff you’ve carefully written is barely used by the team. Why so? Let’s figure it out.

Why they don’t read it

I dunno about you, folks, but I’m a bit of a perfectionist. Several years ago, I believed the best documentation should be nicely formatted, concise, well-illustrated, and written in clear language — and this is not wrong. But all these features make little sense if the documentation isn’t regularly used by those for whom it has been created.

The worst documentation is the one people ignore.

If the team doesn’t react to anything you publish, I have bad news: this documentation (specs, reports, guidelines, etc.) might be already “dead.” Here are several typical scenarios of what may have gone wrong:

1. “Approved and forgotten” — design guidelines were created without team involvement and then approved by stakeholders. After the official presentation, someone checked them out, while others didn’t. Since the guidelines were comprehensive, they looked like a huge reading that would take a lot of time.
2. “A perfect monolog” — amazing design knowledge base inspired lots of team ideas and questions, but commenting was either absent in the tool or disabled. As a result, the discussion occurred elsewhere, in Slack or MS Teams, and soon this chat became a more valuable “source of truth” than the knowledge base itself.
3. “Lone warrior” — design system documentation was detailed and well-structured but didn’t include any links to what other team members (engineers, QAs, UX researchers, etc.) were doing. As a result, it remained just the designers’ resource, and designers had to answer the same repeated questions in the chat or team meetings.

Documentation without constant team involvement is dead.

Documentation is a digital product no less than the actual product you are designing and being paid for. It shouldn’t be perfect — it should work and bring value. And the best sign of this value is when documentation serves as a starting point for constructive discussions between team members and a reliable repository of previous agreements.

Documentation should be an integral part of a team’s life, not a “cemetery” where good ideas come to die.

How to keep your documentation alive

1. Share as you go

When you’ve prepared initial materials, show them to the team as soon as possible and gather feedback. When people are overwhelmed by too many things published at once, they tend to ignore them. For comparison: imagine an Instagram or Twitter account on a topic you like that shares 100 posts within a day after a month of silence instead of entertaining you with 1–2 posts per day.

Gradual updates are easier to follow than getting much information at once.

Example. As a lead designer, you initiated a knowledge base for newcomers. You plan to cover 20 topics — from installing corporate tools to collaborating with engineers. You’ve written only 2 pages, but share them anyway. You get feedback from people who joined the team within the last half a year and now can improve the knowledge base structure.

2. Place it in the context

When your guideline, instruction, or report is ready, insert it where relevant: add a pinned link in the Slack channel of a corresponding project, mention it in Jira tasks, or make it part of the other team’s artifacts, for example, connect your design guideline with engineering conventions. Make it visible where people might be searching for it.

It’s always convenient to have relevant materials at hand.

Example. Your team has regular design critique sessions. You created a guideline on how to conduct such sessions more smoothly, without arguing and irritation. After the document is ready, you ask the critique meeting owner to add a guideline link to the calendar event. Besides you include it in the newcomer playbook so that everyone has it at hand.

3. Let others contribute, not only consume

People always care about things they actively participate in or contribute to. That’s why it’s essential to let them co-create documentation with you. Leave empty parts for team members to fill in, create links between your and others’ documents, and ask people to check if what they’ve told before is accurately reflected in the written form.

Documentation is not the goal; it’s the path to the goal.

Example. You’ve drafted a research plan for the upcoming interviews with users and usability testing of a new design prototype. Instead of proceeding right away, you ask the key stakeholders — designers, product managers, the operations team, etc. — to add their research questions, in other words, what else they want to know about users. Then you can improve the script and deliver results that people will be waiting for.

4. Encourage discussions

As I said above, team participation increases their attention to the subject. Besides, the team can challenge your ideas in the early stages until you go too far in the wrong direction. Let the discussion happen in the context of the document, not elsewhere: encourage people to comment right in Google documents and spreadsheets or, for example, on Confluence or Notion pages.

If people have to say something, I’d better know about it right away.

Pro tip: Team members rarely know how they are supposed to react, so you can help them by asking concrete questions.

• How well does it reflect our previous agreements?
• What other teams or stakeholders should we involve in the project?
• What risks or limitations do you see in this solution?
• How accurate are these effort estimations?

5. Make it cross-functional

Build bridges, not walls. The best knowledge bases, guidelines, and wikis are owned by a cross-functional team, not exclusively by representatives of one profession — designers, engineers, data analysts, product managers, etc. If you are building a common thing as a team, why not document stuff together in one place as well?

Teamwork needs team documentation.

Example. You’ve described how your design team should conduct quality control of new features before their roll-out. Instead of keeping this isntruction as a separate page in the “Product Design” space, you add it to the general Product Wiki, where engneers, product managers, QAs store their information as well. Besides, instead of adding it separately, you inserted it into the already existing page “How we work on projects.”

6. Sometimes, the best documentation is no documentation

Even if you follow all the advice, you may find out that documenting stuff is generally the wrong approach. If you are lucky enough to work in a passionate, close-knit team with high trust and common sense, you can just talk to each other. Remember: documentation is not a “natural” method of collaboration — it’s a business necessity when casual talking is ineffective, for example, when your team is too large and information gets lost. So, don’t forget to check if you can achieve the same effect in a simpler way without any write-up.

Sometimes writing is generally not a good approach.

Example. Your design team often receives ad hoc requests from marketing, sales, and ops teams, which is quite chaotic and distracting. At first, you thought of an official process with Jira tickets, but it would be overkill. So instead, you created the “#design-request” Slack channel and a bot that assigned a designer on duty every week. This designer-on-duty picks those requests and spends a limited amount of weekly hours on them.

👋 Hi there! I enjoy two things — sharing knowledge and drinking good coffee. If you like what you are reading now, feel free to support me via the “Buy Me a Coffee” platform ☕ Thank you! ❤️

What tool is the best for documentation

Choosing an optimal tool for storing and managing documentation often causes a lot of debate. But it’s easier than one may think if you focus on the main thing — the efficiency of team collaboration.

So, what tool to pick? Easy as pie:

• if your team is actively using some tool, take it;
• if the team doesn’t use any documentation tool, go for a contemporary yet simple one so that they can easily adopt it.

Opt for the tool where people will be active.

You may hate Confluence, Google Drive, Dropbox Paper, Microsoft Office, or Notion, but documentation aims to boost team communication and common sense. That’s why it’s essential to reuse an already established info-sharing environment if it’s good enough.

Honestly, there are not many really important requirements to consider:

• cloud-based collaboration;
• formatted text and multimedia content support;
• basic access control and commenting.

That’s it. It’s available in most modern tools. The rest of the features are nice to have, but they don’t matter if people won’t find the tool convenient enough and won’t visit it regularly.

Documentation is just the tip of the iceberg (Photo: Daniel Benjamin).

Of course, it’s fantastic if your team is receptive to change. But in most teams that have been building something for a long time, there is already something in place, and changing the team’s habits may be perceived as an unnecessary effort.

Summary

Even if AI automates writing design documentation entirely or partially, our human perception will remain the same. So, here are the key thoughts on making documentation more effective and valuable:

1. People tend to ignore documentation created in isolation from them, without their involvement and feedback.
2. The quality of design documentation is often perceived as how well it’s composed. Instead, the measure of its success is how often it helps the team to communicate and collaborate.
3. The best tool for documentation is the one that your team is already used to, not the one with many nice features. If the team resists using a certain tool, other benefits don’t really matter.

Hope you find this advice helpful, and good luck with documenting! Feel free to share your tips and tricks in the comments.

• ✍️ Here are all my design articles on Medium.
• 💼 Let’s connect on Linkedin. Drop me a note if you want me to present the topic of this article at a conference or meetup.
• 🏰 Bored by design articles? Check my other blog about photography and overlooked architecture.