Your Documentation Sucks (and you hate it)
Every organisation has the graveyard AKA Confluence, Notion, SharePoint or the dreaded shared drive full of files called Design_FINAL_v3_updated.docx … last edited June 2018
The most obvious tell is onboarding. A new guy joins, gets pointed at the wiki, and within about a day has stopped reading it and started asking people in Slack or Teams instead. Not because they’re lazy… because it’s faster and it’s more likely to be true.
Watch what people actually do
Next time someone has to explain a system, watch them.
They don’t open the wiki/knowledge-base/document. They open a whiteboard, or they screenshot something.
On every incident bridge I’ve ever been on, there’s a moment where someone says “can someone share the diagram” and that’s the moment the call actually starts being useful.
Have you ever, EVER, seen someone share their screen, open up the document file, and start reading the relevant paragraph(s)?
No. Of course you haven’t.
Because your documentation may not suck, it may be fantastic, but it’s detailed and in the modern world of instant answers with AI, or in the chaos of an incident, that is not what you want or what you need.
AI: The Problem and (sometimes) The Solution
Two things happened when the dawn of AI graced us (read that partially sarcastically)
- The cost of creating docs fell significantly. Anyone can now generate 2000 words about a system in about 11 seconds. The AI problem is there is actually less information per word. You can now read an entire page about a system and come away not knowing a single thing about that system.
- We got retrained as readers. We’ve spent the last couple of years asking a question and getting an instant answer. Our tolerance for hunting through a hundred pages to find one piece of information is completely gone. Now we ‘Just ask AI.’
I’m not an AI hater, and I’m not an AI advocate. The same way that I am not a calculator hater or advocate… It’s a tool, and there is a time and a place for every tool — and in the case of AI and documentation, I think it’s useful… sometimes.
For example, lets say you dubiously upload a 100 page design document to Claude and ask it a question, it digests that information and spits out an answer. Fantastic…!
If your problem is “I have a question about this” then AI is the right tool.
But…! If your problem is “I need to understand this” then, in my opinion, AI is NOT the right tool.
The Real Solution
The way we have formatted documentation for decades usually sucks at giving the reader an easy way to understand it.
For me, and for many people I know, the first thing they do when they open up a document is scroll down to the diagram.
So why then, are we burying diagrams, surrounded by “intros” and “executive summaries” and other exposition instead of putting it front and centre? If diagrams are what the technical mind craves why are they not the primary artefact in your documentation?
Well… that was the question I had.
Surprise!!! It’s a plug!
Yes yes, I posit a problem and I also happen to have the solution that I made myself. How convenient.
✨ It’s called Blueprintr. ✨
It started way back last year as a way to make clickable diagrams, because I hated having to surround every shape with text and then route lines around it. Just… yuck.
It’s grown a lot since. The idea is simple: the diagram isn’t a picture in the document, it is the document.
You land on the topology, you click the box, and the detail appears. Config, details, runbook, whatever.
Not on page nine… on the shape. And because it’s a live object rather than a PNG, you can point it at your actual cloud environment or monitoring system, or ticketing system, or CMDB or… you get the idea.
Blueprintr can tell you where the drawing and reality have drifted apart. It’s free, with no limits.
Head over to https://blueprintr.io and enjoy the fancy walkthrough on the homepage, or look at our showcase
I encourage you to give it a go, and let me know if you think it’s any good.
My email is josh@blueprintr.io — I’d genuinely rather hear that it’s terrible than hear nothing.