Documentation is Not the Enemy
‘Let me just spend 1 hour playing around with the app so I can figure out what happens when the user is logged in…and they have this thing turned off…and they have no internet…’
‘I’m a bit afraid of touching that code- Mark knew it best and I haven’t really looked at it before’
‘We designed it to look like this but forgot that it will also appear to users in that other place- and the design we came up with doesn’t work there’
If you work in product, you will probably have experienced some of the above. We experience things like this because making good product and design decisions can be tricky.
Think about a new feature spec. It has 20 requirements that need to ‘come to life’ in your product’s UI. About 8 of the requirements impact more than 1 UI element, with most impacting 2–3 UI elements. This means that, in order to implement those 8 requirements, we can assume 16–24 changes will need to be made to the UI (roughly), and for each of those individual changes we need to make sure we make the right design decisions for that specific UI element, based on its context within the UI and the context of the user. Consider the way a UI changes if a user is logged in or logged out, if a user is part of the loyalty programme or not, if a user is on a particular subscription plan, if a user is in a particular geographical region etc. There is underlying, highly contextual, business logic which we need to understand before we can go ahead and make our necessary UI changes. It can’t be that something works only in one scenario; we need to think about every currently possible case, and, ideally, also consider future scenarios not yet implemented so we don’t need to re-do things again in 3 months.
‘If we decide to disable the button here, it will mean users can’t enter that flow over there’
‘If we make this mandatory at this point in the flow, it means it will break something for existing users in this part of the flow’
‘If we decide to use a lightbox here, we should also use one over there for that requirement…but the UI doesn’t offer enough space in that case’.
Trying to navigate through all this complexity whilst trying to provide a beautiful, thought-out, consolidated user journey, is difficult.
Everyone in a product team should either know or be able to quickly discover, the current state of the product they are working on; the underlying business logic at play, the design decisions made so far and why, the data being used to drive user context, differences based on location or platform, etc. This is not easy and it only gets harder over time as products tend to become more complex over time, as they advance in their number or depth of use-cases, in how many markets they are live in, etc.
There is no silver bullet for this, no golden method for bypassing the difficulty. You have to invest in maintaining knowledge of the current state:
- Architectural diagrams
- Clean, commented code
- Process flow diagrams
- Using tooling to document decisions (Confluence, JIRA etc.)
- Keeping historical specs with good versioning
- Good release notes
Investing time in ‘current state artifacts’ has long-term benefits. Specs and designs can be created more confidently and quickly, everyone in the team will feel more secure about the decisions made and there won’t be the worry that some unknown/sneaky business logic somewhere is going to pop up post-release and ruin the solution everyone worked on for weeks (or months…)
It’s also great for onboarding purposes, in cases of remote work, and to ensure that the product doesn’t collapse when someone leaves the team because ‘they had the most in-depth knowledge about this thing’.
Don’t neglect documentation just because you are working in an Agile environment. It is your map and will allow you to reach your destination much more quickly and easily.
