Why they don’t read it

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.

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 is a digital product no less than the actual product you are designing and being paid for.