Delete Most of Your Docs Take by Matt Pocock

Wanted to share a relevant short by Matt Pocock: https://www.youtube.com/shorts/Fj8DKMbdIzU

## TLDR:

He talks about the tradeoff between asking an agent to understand a system through docs vs code.

He doesn't like the idea of using docs as the source of truth, but as higher level knowledge base (e.g. glossary, architectural decision) and helping agents navigate the codebase.

## Discussion Question:

What information have you found is better represented in the code vs in docs?

## Key Points:

Code should b be self explanatory for an AI agent to understand directly.
Docs are not executable and testable.
Docs can drift out of sync and no longer match code, causing conflicting sources of truth.
Docs should hold higher level context such as discussions and cross functional decisions (e.g. design and architectural decisions)
Use a thin layer of docs to help navigate the codebase ( insert ICM here)
Docs as the source of truth where reading them to understand the code is not ideal

## Relevance to my work:

I am trying to understand how to implement ICM for ongoing app management and improvement (read as software factory).

This tradeoff between holding truth in code vs docs is top of mind.

For example, I'm currently doing a significant amount of UI work. In ICM, i have defined relevant user workflows and linked them to their relevant components. The workflow documentation provides higher level context and intent.

However, I am still trying to determine how much documentation is enough. I want to keep reasoning behind decisions so future work respects them, without creating a second representation of the app.

Some simple examples where the rationale is not always obvious from implementation:

We display a timestamp here because that level of granularity is important for this workflow.
We use green rather than blue here to distinguish completion vs continuation action.
We place this data together on the same row to reinforce their connection.

4 comments

Delete Most of Your Docs Take by Matt Pocock