Collaborative interaction documentation for UX, QA and Dev
As complexity of interactions increase, so do demands on UX (user experience) designers to produce appropriate documentation to communicate this complexity. When you’re dealing with enterprise applications, this complexity is inevitable because users perform an especially complex set of workflows. As a result, the richness of the interaction rules you define increases.
If we put together our documents well it can ease implementation, inform QA and help technical writers. As each of these roles have different expectations, we often all use separate pieces documentation that are disconnected, but this means content is duplicated and compromised. For example, a QA might write separate test scenarios and a technical writer might jot down what they’ve read from Jira stories. As implementation of stories happens, things shift and details of a feature could be spread across 5 stories and that single source of truth becomes more and more important. Like the game telephone, the more you remove information from the home source, the more distorted it becomes. More than that, it seems like duplicated effort which most of us can’t spare.
So my dream solution is this: QA, Dev, UX, Tech writers all know, and contribute to a single place where all the details are kept which results in:
- better communication
- better results for the user
So how might this work? Let’s start with the interaction design process from the UX end: To deal with interaction complexity, UX designers use the power of scenario mapping. This can be high level (like, a customer walks into a Starbucks..) but also more specific (like, a user presses cancel after executing three over actions which haven’t been saved yet).
Detailed scenario mapping helps UX check and recheck the strength of our designs, seeing if our interaction model actually makes sense. This process helps us identify edge cases; those weird sequences of events that aren’t immediately obvious. However, try as we might, we never think of every single one.
This is where a QA (quality assurance) specialist shines. These are creative system breakers have a keen sense of how to follow of complex sequence of events in order to break your product. They are beacons of interaction thinking and can dazzle you with their scenarios, so why not leverage these brains and collaborate on interaction documentation?
They can take your edge cases just that little bit further and assist you in stress testing your design before any developer starts implementing. You can ask them what their test cases might be when the design is being implemented. This can be a great way to come up with different states and conditions you might not have realized existed, as well as help you think a little bit more like a QA. Collaborating with QA can also be a useful communication mechanism, so that when it comes to QA stage, you have well informed gate keepers to releasing the finished product.
QAs aren’t the only brains that can improve your documentation, developers, especially UX-minded ones can help you improve your documentation as well. These guys fundamentally know the product inside and out, they also likely have a different mind from yours, one that doesn’t miss a single colon or backslash. They typically work within Agile or other project management styles which grounded in frameworks which call out assumptions and have very clear acceptance criteria. They can also grill you on your expectations around weird edge cases.
Benefits of Collaboration
This sort of collaboration can be useful on a lot of levels. First and foremost, it helps to have absolute clarity on how your design/feature/widget should function. You are enabled to work out even further kinks because of their input, before the expensive implementation is in full swing. You can’t predict every single question that will arise, but you can certainly work out a lot of things before you’re put on the spot. This will reduce weird decisions that get made on the fly resulting in interaction patterns that don’t sit right.
You also get a great opportunity to take in information from team mates that is defined in specific parameters. Getting and giving feedback is an art, you have to be cognizant of how effective getting the right type of feedback from the right people is. Asking for input on things that people are knowledgable about is great, asking for input on everything as a blob is not.
Collaboration helps build a collective brain where important things are considered when making decisions. If you’re a half way good ux designer, you’re flexible and thoughtful about the interaction choices you make. You don’t always want the most difficult implementation because that’s how you imagined it, you’re willing to compromise for the smaller things and fight for the things that are most important.
When do you collaborate on documentation?
You’ve sketched and written a lot of things down, dismissing other options. You have put in enough thought that you have something real to discuss with your collaborators. Showing half thought out stuff won’t be a productive use of their time.
So, your idea is quite well developed but not finalized. You’ve validated need, use cases, and your approach to solving the problem has sound rationale. Now, you’re trying to push it as hard as you can and see if it gets crushed under the pressure of edge cases and detailed developer questions.
I usually start a design document that gets gradually more and more clear (from rough notes to detailed notes, tables, images etc). At the stage where I want to know if it makes sense to others I get them to check it out. Lots of UX stress tests have already happened, so you’re in a position where you’re hungry to iron out the granular details
The Dream Document
The dream document for a complex feature for example:
Intro: need/problem, design rationale, basic description of how if would work l
Rules: specific but important design rules that developers need to know ex. Multi select is not allowed, by default container is collapsed, etc. these rules are built by design and dev
Interaction scenarios — these scenarios including basic CRUD and edge cases are built by UX and QA.
Visual design — housed externally (url) or embedded.
The children documents, which are linked to in your source document include detailed documentation like: help text, user facing technical documentation, implementation details, any UX research/analytics.
We as tech people seem to always ask the question: how do we actually practice ux? How do we actually do it? Working in ways like this is how we get closer to an Agile, inclusive ux practice in our organizations.
Do you join together your documentation in a way similar to this? Or do you see a better way? Tell me what you think.
