PITA 072
How do you keep track of knowledge?
Documenting decisions = moving from AS DISCUSSED to…
We use AGILE as an excuse not to document. That’s not what it means, people
Is there a single source of truth? Very often, there is not
Architecture Decision Records (ADRs) - we had to formally document the Decision rationale, and that helped - at least, architecturally
Confluence often has sporadic documentation. Now some is in Google Docs, Figma, PRDs… Everyone does it differently. There’s no ‘there’ there.
How much fidelity do you need? How much turnover is there?
How long does it take to get a new person oriented?
There’s a variance between what was discussed/decided, and what was done. Intentionally or not. And we often lose the intention. We can use Claude Code (or similar) to help us understand WHAT it does, but rarely the WHY
Current reality: single source of truth is code… but that only shows what IS, not what MIGHT HAVE BEEN or WHY - or even if that was the intention.
Used Claude to analyze repositories and generate functionality documentation: Code reflects actual strategy vs stated strategy; Strategy changes require documenting: starting point → learnings → current direction
What order do you work in? How is your process changing?
Coding was expensive, now it’s cheap. Build quickly on a PXD, then refine
10 years ago, we sort of did this - mini-design sprints (kind of), discover where we need to push tech, experience, etc. I’ve got a new team doing that again, but what’s different is using AI-based tools to support discovery, prototyping, and the art of what might be possible. And it’s been fun. I’ve learned a lot - more than I have for years.
And what issues are coming from the way we work now?
Some companies, the engineers want the decisions to be made for them - they just want to code.
We still need focus on both performance (health) as well as business (success) metrics. Despite the swarms of agents and compute resources, we still need to worry about optimisation - even at early stages. Outsourcing is becoming increasingly expensive, unreliable, and many can do GOOD ENOUGH on prem these days.
Three levels of debt identified: Technical debt: code quality issues; Product debt: decisions misaligned with current reality; Business debt: imposed rules affecting other areas
But also Cognitive Debt- when you have so much changing/developing at once, keeping on top of it all