#UX101: Producing Design Documentation

How much design documentation do you need to produce? Do you make pixel-perfect wireframes that detail every single interaction and behavior? Or do you create mid-level documentation and leave the details to the development team? The answer, of course… depends.

I know many designers who feel they HAVE to flesh out every single aspect of the experience, and so they spend hours and hours making sure everything is spelled out and documented. They produce hundreds of pages of design specifications, which are then handed over to the development team to execute from (and the QA team to test with). This reflects the classic “don’t make them think” attitude that some UX professionals have towards developers – and, to be fair, many developers have the same attitude. This extreme level of specificity, though… I think its overkill. It ends up increasing the design lifecycle as well as increasing development and QA time.

On the opposite end of the spectrum, I know some designers who do a cursory job of design documentation and do only the bare minimum. It’s not that they are lazy, they just don’t like doing design documentation (full disclosure: I’m not a fan of design documentation, either). When this design documentation is delivered, developers often have many questions about use cases or exception handling that is not detailed out. Just like documentation overkill has issues, “underkill” like this produces lots of problems.

To me, the best design documentation is like the best design: It aligns to the needs of the users and solves problems for them. For developers and QA team members, this means getting to know them, understanding their process, and aligning with what they need. This means having a certain degree of flexibility about how you do things (and there may be some negotiation). Basically, document the design as much as you need to in order support your team and ensure the vision of the design is properly executed.

Additionally, there are some design documentation “best practices” I have identified over the years, and hopefully these will help you in your work:

Document standards instead of create documentation

I’m big into efficiency, and one approach that helps you be productive is to define design standards that should be followed throughout what is being designed. These overarching rules can be used to answer any questions and resolve any ambiguity. Try and make these standards specific enough that they aren’t platitudes, and are practical and actionable. Look up examples from Google, Microsoft, Amazon, and more to help come up with your standards.

Build (or leverage) a pattern library

Once of the great principles of development is the goal of “write once, use everywhere.” This means coding or leveraging standard libraries that save time and effort. You can do the same thing with design documentation by leveraging existing pattern libraries and/or creating your own. This way, you will be documenting a UI element once… instead of every time it appears on a screen.

Produce design documentation that is used and useful

Don’t create design documentation that you think is what is needed, based on what you have done before… Make documentation that aligns with what the team will actually use. Don’t spend hours building out a complicated sitemap that will look really nice framed on the wall that no one will ever apply. Make documentation that matters, and apply user-centered design techniques to ensure that what you produce is usable for the recipients.

Don’t replace communication with documentation

Don’t throw design documentation “over the wall” and hope that documentation will be enough – walk through the design with the team and explain how it is supposed to work. If you are in an Agile team, this is a constant process and it results in a better design. If you are doing “waterfall”, you will have to set aside the time to do these walkthroughs… Do it as soon as you can, to understand both the level of documentation needed as well as to get feedback on the design that can you can apply to make the work better.

Focus on design, not on documentation 

While you should always put aside and plan for sufficient time to document what you have designed, understand that your focus and most of your time should be sped designing solutions and focusing on user needs. Spending all your time documenting instead of designing will result in a false sense of accomplishment – you may have a big pile of documents at the end of the day, but if the design spelled out in those documents don’t help people accomplish their tasks and do things faster and better… well, it’s a hollow victory.