2025-11-07
Lecture Friday: What Nobody Tells You About Documentation
This is the conference talk behind The Documentation System. This is my all time favourite framework for organizing documentation on a project. It builds a little 2x2 matrix based on practical versus theoretical and studying versus working to categorize documentation. Really helps provide clarity on what you're writing and where it should go.
There's often times to break with this strict breakdown. For example I love having a dedicated page to talk about the project explaining what it is and why you should care at the top of the documentation and outside this structure. FAQs also tend to sit outside just to be really easy to find. It's fine to break with this structure when it makes sense, but having this as the backbone of the documentation has really improved splitting documentation up. To try and stop having stream of conciousness dumping documents.
I would strongly suggest not throwing everything out and starting again. Just start by adding this structure to your project and link (don't move) the existing documents that already fit this structure. That's already a lot of work and doesn't destroy what you have before you've fully built the replacement. Next, you need to build buy-in. If people are going to keep writing documents the old way (usually randomly in wherever they think makes sense) then you'll never converge. Getting buy-in from the team about this system means all new documentation will be built starting from these viewpoints. Even if the folder structure is later abandoned, just having these use cases in mind when writing documentation prevents making information soup.
Once all that's done you can then begin refactoring documents as you update them, splitting them into new documents inside each of the relevant sections. Over time, if you have analytics, you should start to see more and more people reading documents from the new sections and less from the old. Whenever you see a document outside this system being used often, refactor it into the system. If you don't have analytics on your docs, you probably should. It's invaluable to help find what documentation is having a real impact and what documentation isn't.