Quality documentation

Coming from a design background, I feel strongly that the actual design and experience of the documents contributes to both their usability and the level to which they are valued by internal and external clients. I am sure I am not alone in having this view. So, having seen many examples of horrible, unclear documentation, I am keen to get on my soap box about this. 

A UX’er could be called on to create a number of documents, from a sitemap and wireframes to flow diagrams and concept diagrams. And, of course, not every UX designer has the skills to make every output a work of art. 

I have seen some awful documents, but, to be honest, the awfulness doesn't come from the lack of design finesse as much as from the author trying do something they are not familiar with. I’ve seen outputs from IA’s trying to make hardcore tech specs by using language they’ve seen in other peoples documents and not understanding it. And an awful hash made by someone who was wrestling with a content audit ad clearly loosing the battle. 

So, what is good documentation?

• Its clear: it speaks clearly to the audience it is meant for.
  
• Any one in the team can pick up your outputs and understand your thinking on the subject, without having to ask you what you mean.
  
• Its pleasant to use. Anything that gives people a headache is definitely going in the wrong direction. 
  

Why is it so important to document well? 

• Good documentation helps you communicate your ideas clearly.
  
• Documents have a habit of drifting out of your control, so they need to be able to stand on their own two feet in what ever company they find themselves in.
  
• If you ever want to change jobs, you are likely to have another UX’er reviewing your work - and sloppy work will count against you. 
  
• Someone else may have to work on them. They won’t think well of you if they inherit a pile of s**t!

My advice is this:

1. Know your audience. A solution that suits board level directors may not be right for the development team. A one size fits all solution will end up suiting no one well. You may have to adapt documents to suit the people who will be using it.  
   
2. Ask around. If you need to do something you are unfamiliar with, ask someone who is. 
   
3. Use the internet. If there aren’t a hundred examples of what you need to to, I’d be really surprised. 
   
4. Do follow the crowd. As usability resides with the user, it make sense to utilise what’s familiar to them and build on that - rather than having to educate them each and every time you present to them.  
   
5. Consult a book. Dan Brown’s book on “Communicating Design’ covers the basics of UX deliverables quite well. He has a collection of examples on his website, too.