I'm Not a Tech Writer. I Built a Docs Standard Anyway. |
I picked up a docs problem no one asked me to solve and ended up somewhere I didn't expect. |
The Accidental Documentarian |
Given my Catholic roots it feels fitting on this fine Sunday morning to start with a confession. |
I have no formal training as a technical writer let alone in information architecture. |
In late 2024 I picked up documenting our internal GraphQL instance. Nobody asked me to do this. It's not as if I am an expert in GraphQL. In fact I was seen as somewhat mistrusting of GraphQL. While I could see the appeal, it felt to me that a single endpoint was an easy sell. However you have to understand the schema, the query language, and the mental model before you can do much at all. The tradeoff to me felt like a unified interface for onboarding complexity. |
To say the docs were rough was an understatement. |
Active voice — I didn't know that was a thing. |
Following best practices - definitely not. |
At that time we had access to an early ChatGPT instance. I had no idea what prompting was and I spent days throwing the schema at AI trying to figure out how to write queries to solve a particular problem. CoPilot was a twinkle in my corporate eye. It's easy to look at Stripe or other documentation darlings like Vercel and think "just do that".
|
The Question I Hadn't Thought to Ask |
This act of writing forced a question that I had not taken seriously before: what does good documentation actually look like? |
Meanwhile in the organisation we were investing in Backstage so the timing felt right. I drafted a Confluence page with the lofty title which was a mix of strategy elements - problem statements, goals, business outcomes and a roadmap for myself. |
I drafted a Developer Documentation Architectural Standard for and by technology teams. Alongside this I published a compendium document of best practices which recommended the Diataxis framework for information organisation, the use of The Good Docs Project for templates and some recommendations on documentation storage. |
I launched a community channel in Slack. I built the AI Docs Coaches - structured prompts that asked eight questions and produced recommendations in the standard such as an mkdocs file, a README, CONTRIBUTING guide and some other items. I shared it. |
In reality this should be a CLI or baked into templates on repo creation but why use a toaster to make toast when you can use a rocket. |
AI all the things. <snark> |
I moved onto our agentic framework because this is one of our key strategic pillars and I figured it was a neat way into learning about AI. I helped refactor the teams existing docs into more structured markdown following the Diataxis Framework. |
The GraphQL docs are now being handled by a professional tech writer. |
Why Any of This Actually Matters |
The lesson is that you don't need permission to build something worth building. Success for me is that I raised my own bar with understanding technical writing which is an invaluable skill. I started to understand why docs quality matters in a way I couldn't articulate before. |
I now see documentation as AI infrastructure. Without clear, structured, and maintained documentation, AI systems cannot operate reliably, safely, or at scale. Documentation debt doesn't disappear when you adopt AI. It compounds. The documentation your agents read is an engineering asset. Start treating it like one. |
This post is my Docs as Code origin story. In the coming weeks I will go deeper into building an agent ready docs project. I still have not figured out how to write like a technical writer. |
Same bat time, same bat channel. |
| |  |
|
