I Document Like a Professional at Work. My Side Projects Are a Disaster.

It feels like documentation at work is more of a checking the box exercise sometimes. My own side development projects brought a lot to light.

I write business requirements documents. I write functional specs. I write process flows, configuration workbooks, user guides, and the occasional runbook that lives on a shared drive forever. None of it because I love writing documentation. I do it because there is a project manager waiting on a sign off, a client who will not accept go live until the deliverable is in their hands, and an auditor somewhere who might eventually pull a thread.

So I check the box. The BRD gets written. The functional and technical designs get reviewed. The process flow gets diagrammed in whatever tool the client has standardized on this quarter. Then it goes into a SharePoint folder and, if I am being honest, half of it never gets opened again.

I told myself for a long time that this was the nature of the work. Documentation is overhead. A tax. Something that exists to satisfy people who are not actually doing the building.
Then I got a little too deep in building a side project on my own time.

The README says "wip lol." The .env file has variables called OPS and OURA_THING.

There is a folder on my desktop named "projects_old" that I cannot describe the contents of without going in there. I will not be going in there.

Same person who, two days ago, delivered a configuration workbook to a client.

I never thought much about the gap until I started building MCP servers.

Where the chaos meets the wall

For anyone who has not played with this yet, the Model Context Protocol is a way to expose tools, resources, and prompts to an LLM in a structured format. You write a server, you define your tools, you give each one a description, and the model uses those descriptions to figure out what your tool does and when to call it.
The description is not a comment. It is the interface.

It is, weirdly, the closest thing personal projects have to a functional spec. If your tool is named get_data and its description is "gets data," the LLM is not going to know what to do with it. It will not call it. Or worse, it will call it at the wrong time for the wrong reason. The model needs to understand your tool the way a business analyst would understand a process step. Inputs, outputs, when it runs, what it depends on, what it does not handle.

I sat down to build a small MCP server for a personal experiment. Nothing serious. A few tools wrapped around a service I use for fun.

And I could not write the descriptions.

Not because I did not know what the tools did. I built them. I knew exactly what they did. I had just spent so many years writing personal projects for an audience of one that I had lost the muscle of describing anything to an outside reader. Every description I wrote either assumed too much or said nothing. The first draft of one of my tool descriptions was something close to "fetches the thing."

If a junior consultant on my team turned in a technical spec that read like that, I would send it back.

What the box checking was actually doing

Here is the part that took me a while to admit. The BRDs, the functional specs, the process flows, the workbooks I half resented while writing them. They were not just there to satisfy a project manager. They were forcing me to think about my work the way an outside reader would. What does this do. Why does it exist. When does it run. What happens when something goes wrong. Who needs to understand it.

I was doing that work every time, even while I was complaining about doing it.

At home, with nobody making me, I never did it. I built things and assumed I would remember. I did not. The MCP server forced me back into the same questions I answer every day at work, except this time there was no project manager. Just a model that needed to understand my tool well enough to call it correctly.
What I am actually doing about it

Probably not enough. I have started writing tool descriptions before I write the tool itself, which is a small but meaningful shift. It is the personal project equivalent of writing requirements before you build. If I cannot describe what the thing does in one clear sentence, the thing is not ready to be built. That alone has caught a few half formed ideas before they became half built code.

Turns out the box was doing more work than I gave it credit for.