Nobody reads the Markdown

Our repositories have stopped being just a safe home for our codebase, they have become a noticeboard.

Markdown files have appeared everywhere, each one containing another set of instructions for the agents now wandering through the project like contractors on their first day, nodding confidently while having no idea what they are doing.

Look at any modern code repository and there they are.

• AGENTS.md
• CONTRIBUTING.md
• ARCHITECTURE.md
• DECISIONS.md
• HOW_THE_IMPORT_BIT_WORKS.md
• READ_THIS_FIRST.md
• READ_THIS_FIRST_ V2.md

This isn't necessarily a bad thing, and here is why.

Documents are one of the best ways to give AI agents context. Models can write code extremely well. They can translate specifications into implementations, follow patterns, produce tests, and confidently invent a function that already exists three folders away.

However, they are less adept at knowing what we meant when we gave them the prompt that generated the specification in the first place.

It is in this intent - what we actually mean – that most of the software's value lies.

It's the work around the work.

In The forklift and stapler, I wrote about task engineering.

I wrote about why we need to stop giving AI systems tiny instructions and start giving them designed pieces of work; why we need to give them tasks.

To do that, we need to paint the picture of what we need, define what 'done' looks like, and leave room for the agent to make decisions.

Which sounds excellent until you realise what we have invented.

More documentation, a developers' arch nemesis.

We don't expect developers to write every word themselves. We have AI now, and we can generate 17 pages of technically immaculate prose before someone has finished saying, "Should we document this?"

But generating documentation is not the difficult bit. The difficult bit is taking responsibility for it. And that responsibility is sitting firmly on your shoulders.

Agents are your teammates

Your agents can read the code, make changes to it, and sometimes complete an unsettling amount of work. What they can't do is absorb the invisible information that exists between us humans. This includes historic organisational decisions, past compromises and unwritten rules (i.e. the thing nobody touches because Sarah once said not to).

For agents the code is visible and readable, whereas the understanding and intent is not.

Documentation is what we use to fill the gaps that exist between the code of the software and the intent of the system. We need documentation to tell the agents how the system is supposed to work, any constraints that exist and where previous developers discovered holes in the floor.

Your tour guide is operating with an outdated manual

Imagine the documentation in your repo is a tour guide showing a new employee (your agent) around a large factory. Reassuring at first.

"This way to the accounts teams."

"Safety equipment is stored in the orange cupboard, marked 'Safety'."

"When you finish your shift, press the big red button beside the loading bay."

But what if the documentation hasn't been updated for years, the accounts team changed buildings, the safety cupboard now contains Christmas decorations and a printer nobody remembers buying?

As for that red button near the loading bay, it's now blue and pressing it releases a thousand litres of custard.

Armed with the documentation, the tour guide speaks with unwavering confidence, but they are catastrophically wrong.

If you gave that same documentation to an agent and asked it to modernise the factory, things would go wrong fast.

Documentation generated (or otherwise) without ownership is more dangerous than ever because agents trust the documentation.

Trust is new development dependency

For agents to work effectively across a team, the team needs to trust each other's documentation. This is not simply trust that a document exists. It is trust that a document matters, that it is accurate, it has been reviewed, and trust that it will be kept up to date.

This work cannot be entirely delegated to the AI that generated it either, in the same way you wouldn't ask someone to write their own performance review, approve it and award themselves a pay rise accordingly.

An agent can draft a document, review it against code to find inconsistencies and suggest improvements, but a developer needs to decide whether the document reflects the system, whether it reflects reality.

A key component of our new role is judgement. The model does more of the typing, we do more of the judging.

The hopefully useful bit

I wanted to share a checklist for evaluating your documents, because most of the bad ones look fine until you check them.

When you are next working on a document for your project, ask these 5 questions:

1. Does this document have a specific purpose? Can you explain who uses it, and what decision or task it helps them complete?
2. Is it still true? Check it against the code, configuration and current behaviour rather than trusting its confident little Markdown smiley face. As I mentioned above this is something AI can help you with, just check its work.
3. Does it explain the intent as well as the mechanics? "The system does this" is useful, but "The system does this because changing it would anger the payment processor" completes the picture.
4. Is it concise and is it understandable? No document is improved by becoming a complete oral history of the repository. A document is also useless if only an agent can understand it. Make sure your non-agent team members would know what the document says.
5. Is it clear when it needs to be updated? If the document can become stale without any obvious trigger or owner, it will.

If a document fails any of these checks, you should fix it or delete it if the content is no longer relevant.

Doing software wrong in plain text

Markdown files (or other flavours of document) have become very important, especially as agents take on larger pieces of development work.

But this only works when the documents can be trusted. While AI has made documentation almost free to produce, it hasn't made it any less expensive to own.

We as developers need to review the documents, challenge them, and occasionally remove six pages of total nonsense before another agent mistakes it for the constitution. We need to own them, not just ship them.

Otherwise, we have not painted a better picture for our AI teammates, we have simply automated the production of un-helpful content at a scale previously available only to large government departments.

As usual, we will be doing software wrong.

But in Markdown instead of C#.