Programmers will document for Claude, but not for each other

Yeah, because Claude is willing to read other documentation in order to understand mine. When I'm asked to write docs for humans I have to work four times as hard because 3/4 of that work is getting the audience up to speed just so I can start documenting the actual thing. And then they don't read it and ask me to explain it to a meeting anyhow.

I've written so much documentation over the years, and humans always come and ask me questions that the documentation answers, but never ever read it.

  1. Immediate better output from the machine OR...
  2. Being sidelined for career promotions because you spent so much time making sure documentation was accessible while everyone knows they can ask you instead of reading it, and you will answer.

Claude never complains.

In my experience the text for the Claude has only one requirement - the intent and meaning must be there.

The text for Claude doesn't need structure. Doesn't need style. Doesn't need formatting. Doesn't need deeper thought. The only important thing is that it includes somewhere somehow the relevant bits of information.

The quality of prose I throw at him is below what I would show to any other human. I just turn on my microphone, keep dictating whatever comes to my mind and I think might be relevant. After this is done I may or may not ask Claude to rephrase what I wrote before keeping it as memory.

On the other hand people judge you for what and HOW you type. They complain about it.

It's in my experience that people will generally judge a programmer much more for the quality of his outputs than the number of them. So if your target are other humans - it's better to have no docs than bad docs. For claude it's the other way around.

A lot of developer documentation is effectively write only. It gets written, often at great cost. But it doesn't get read a lot. It doesn't get a lot of feedback. It's typically out of date. And the lack of documentation is not really blocking anything important anyway.

If you are ever on a project where somebody goes "Somebody should write some documentation for X", you should counter it with "Great idea, get on it!". Mostly nothing will happen. It's rather thankless work. Some people are more proactive on this.

I actually tend to write documentation for myself. Because I'm old and wise enough to realize that if I come back to a project in two years, I will have forgotten most that I would need to get back up to speed quickly.

With agentic coding tools, it's different. The documentation helps. And it gets added to even if you don't ask for it. Which is nice. And you can get a lot of documentation added with a few simple prompts. Which makes it cheap and easy to generate.

Because Claude actually reads what I wrote. Other programmers, not so much.

I had an online art class right before Stable Diffusion came out. After SD workflow got well known among the art community, I asked the teacher what's the difference between AI image-gen and human artists. His answer (paraphrased): It's easier to make AI learn.

Programmers aren't documenting for Claude. Claude is documenting for Claude. Programmers are, at best, reading the documentation Claude wrote for itself to ensure there are no glaring mistakes.

Generating tonnes of documentation is easy, but it can easily get outdated and so much that no one would read it. Ideally, code should be the single source of truth. Documentation should be generated dynamically and upon request to not go stale. The amount of detail and how far to dig in should be up to the end user.

It's not just documentation. Everything that makes programming easier is now suddenly valued, because wasting tokens is obviously worse than wasting your employees' time.

Because there will not be any point of explaining for humans, it has to be explained so AI have all the context necessary to re-explain to a human, adapted exactly to match current skill/personality and so-on.

I used to write extensive docs, now I solely write docs (I mean, the typical automated model Zoo do it for me) so AI know what to do later. Even inside the team, we don't really explain (except very high level concepts) anything for onboarding because the onboarding is directly on the harness, the file structure of a repo isn't even really checked anymore (probably no point, soon enough) as most people will end-up entirely on a chatbot anyway, it's start to be hard for me to even justify going out of our own internal harness windows (I have 16 to 32 of them open with 8 monitors).

I genuinely think a massive wave of depression will hit "tech workers" when they might realize that all our greatness (programming, arguing, planning...) will just be to prompt all day long and we will just be all in a "chatbot" in the end.

I have a project where I asked the coding agent to write a design doc for each new feature. It now has 80 or so design docs, which aren’t kept up to date, so it’s a historical reference that we don’t go back to in practice. At some point I will probably delete them.

In a different project, I instead have it maintain a project overview and a couple other docs, and we delete plan.md once the work is done and the docs updated. I like that better.

Half of the purpose of me documenting things is to make certain that I fully understand the problem and its solution.

As I write out the explanation, if something doesn't make sense, that is a prompt for me to dig in and understand more fully either what I am supposed to accomplish and/or how I intend to do it.

That applies to everything from single-line comments on up to project READMEs and polished, customer-facing documentation.

One consistent frustration I have had over the years is that so much code is not documented or (worse) poorly documented. If there is a silver-lining to AI-assisted programming, it is that clear writing of goals and proposed solutions are rewarded with more accurate outcomes. It should have always been thus. but I'll take it.

After 12 years of trying, my manager has finally convinced the boss that dev docs and user docs are different, because Claude made different documentation for different audiences.

When I was in tech support I wrote down the solutions to tickets, it took training the other support techs to read the knowledge base. It took 6 months but support call duration dropped 40%.

It also took training to get customers to read the knowledge base. That reduced calls by 60%.

Documentation has been disregarded by management since the 70s. Now suddenly it's important and its costing them a lot to try to play catchup.

As a human, I'd rather just explore the code (which I tend to trust more than anything written beside it) myself.

The bot though- I don't want it to waste a bunch of tokens exploring nonsense. If I can write a few lines of text that will help it get straight to where I need it to go for 99% of work, that's a win.

It feels hand-holdy when done for the bot. I don't want to hold my follow human's hands.

I noticed this! CLAUDE.md is one of my go-to places if I want to read documentation, now. It's usually much more to the point and more accurate than whatever was intended for humans.

Documentation is worth it only if it is read. If your coworkers don't read/remember/respect the documentation process then people tend to not keep the docs up to date. Unless the docs are for users who you don't want to come to you at all for support.

Claude is a better reader. I have to just tell it to read the docs/specs sometimes.

yeah, because claude will actually read the docs

>I review these overviews carefully and make edits as necessary before I check them in. It's my signature on the commit, and my bank account receiving the paycheck, so nothing goes into the repository that I haven't read carefully and understood, same as if Claude were a human programmer under my supervision.

Commit enough of this documentation, and your bank account wont be receiving the paycheck anymore ("position eliminated, they AI can now do his job").

Claude A) reads the documentation and B) needs the documentation C) can write the documentation quickly. None of which is true for your and your coworkers, at least not consistently.

> I keep seeing programmers say how angry it makes them that people are willing to write detailed CLAUDE.md and PROJECT.md files for Claude to use, but they weren't willing to write them for their coworkers.

Similar for adding static type checking, which makes it easier for AI and coworkers to understand the code, catch mistakes, and to refactor. And now there's coders willing to add static type checking to help AI but didn't see the benefit before for some reason.

I noticed this while programming with LLM assistance. It's easy to put effort in for the LLM because there is immediate positive feedback: improving the context gets better results. Folks have mentioned other reasons LLMs get better support like docs for humans don't get read and don't improve KPIs.

I think this might lead to more literate programming. The main challenge with LLMs is humans understanding the code, which lp helps with. Also, it includes the relevant context with the code itself. Both of these things help humans and LLMs.

I've been trying it myself and I think it's working pretty well. The only challenge right now is that it is difficult to get models to output code literate style. The output from LLMs tends to open a code block and put everything in it with a ton of long comments, rather than create several blocks with prose in between. [A caveat is that I don't have access to SOTA models.] My plan is to add an agent that just focuses on the style.

Don’t take it personally. Programmers are not documenting “for Claude”. They are documenting for anyone using Claude.

Writing and reading docs used to be incredibly time consuming, and programmers often didn’t read them. Now you can all but guarantee a doc will be found and read and followed if it’s relevant. The ROI on docs is high now.

The author's perspective seems strange to myself and likely my teammates. We use Claude to document our development work and it seems to me, my manager and likely my teammates, that our documentation services both ourselves and LLM context effectively. Perhaps I misunderstand the perspective being shared as our documentation is generated with Claude collaboration itself. To be clear, we have effectively moved our project documentation markdown from the repo top level into a .claude/docs tree itself. A distinction of audience, particularly as we have system prompts that provide documentation generation standards, doesn't seem to me to be intrinsic here -- our documentation is effective for both people and AIs. We also use system prompting and skills to maintain existing documentation at pull request time.

Some people like to brag about how productive they have become with AI, but I see them spending a few hours a week adjusting which model to use, trying the new shiny harness or writing Claude skills.

Are you really more productive if instead of coding you are spending your time tweaking the AI to do what you want?

There was a growing consortium of developers who bought into the idea of "self-documenting code." They actually considered you incompetent for writing documentation and relegated this to roles they deemed inferior. I wonder what these types of developers think of this?

It’s all about the incentives.

Unfortunately, companies often measure developers by their own PRs.

An unfortunate outcome of this is that writing docs for other developers isn’t really incentivized properly (and with stack ranking, you might even say it’s disincentivized). Writing docs for Claude, however…

We are now writing specs for important components and algorithms, and spend quite a bit of time aligning on them before implementing the production version. Those specs are often informed by vibed prototypes, but usually it’s also two or more people really thinking through an algorithm, and aligning with interfaces to the adjacent systems. They are usually very information dense.

I don’t believe spec driven development is a good idea though. The architecture should be made with intention as well, or I feel we‘d end up with whatever happens to be ranked highest in the latent space. But the specs are great to align cross platform teams behind shared concepts, and they are a good input to automatic reviews.

I've always tried, but usually work demands make it difficult to stop and finish. At least these days I can hand off documenting to an LLM. If anything, I have to tell it to back off a little to make it more readable for human eyes.

1. Claude's productivity is your productivity, but team's productivity is not your productivity.

2. Claude will actually read what is written (well parse for autocompletion, not actually "read", unless you are under AI-psychosis).

Time vs effort balance is very different for the two cases.

-- writing documents for each other takes weeks - write the document, give people time to review the document, discuss, update on review.

-- writing documents for Claude takes minutes rather than hour - AI is used to assist in writing specs, personal instead of collective review/approval process.

Also beneficiaries are different:

-- when you write spec for Claude - you benefit personally, you have higher chance of getting code you need from ai coder

-- when you write spec for the company - the company is the main beneficiary, it get higher chances to get teams on the same page with the change

It's pretty simple, really.

Before agents, good documentation wasn't a metric that got you promoted or warranted a raise. Writing features takes time, so developers didn't do it.

Agents require really strong documentation to work effectively. Almost every organization is volun-forcing their devs to use agents. Good documentation is now THE performance metric, except it's less about performance and more about keeping your job. So developers now write strong and extremely detailed documentation.

I wonder how tech writers feel about all of this.

(btw, most of that super detailed documentation is AI-generated, so there be dragons.)

I was going to mention this too. Some of the API documentation I've read is downright puzzling, but whenever I see docs written for an LLM they always contain the exact relevant information I need to start working. [1]

I suspect the human docs are how they were taught to write and the LLM docs are what actually worked for the LLM.

[1] https://developers.openalex.org/guides/llm-quick-reference

I've noticed that things like "decision documents" and complete feature or service {proposals,white papers,"one pagers"} have become acceptable since the start of the AI {boom,bubble} in a way that they weren't before. It's now seen as valuable for an engineer to lock themselves in a room and write 4 pages of specs for something they're working on, since the expectation is that this will speed things up when doing the actual coding. I have personally always liked to work this way, but have had to hide it. Now, even if I'm not really leaning on the AI for implementation (and not at all for writing the {spec,vision document}), I'm seen as some kind of LLM whisperer, even if I'm more on the Luddite side.

In engineering of all kinds (or at least the ones I'm familiar with), nothing really beats calmly sitting with your thoughts, stating a problem, then getting up and walking around while you think about it, then sitting back down to write down a possible solution, and then asking colleagues to read it.

I have at both ends of this problem.

Documenting but people not reading and still asking question. I have tried some what successfully asking them if they have read the document. Because sometimes people are unaware it exists. There are those who insist on answer and these are people who I give delayed response.

On the hand I have seen people who say stuff like why don't you read the code. These people are now using AI to write documents.

I've always found something like this funny: programmers writing detailed code for a computer to use but not detailed documentation for a human to use for using the code... there were frequently gaps in logic which they'd never allow with code itself

The form was usually something like "do x" where x was composed of "y + z" but how to do y or z wasn't explained

It is hard to incentivize docs, and often when there are incentives they make writing docs painful (sharepoint) or time intensive (run books).

I am not convinced that just adding llm summaries to a commit will have long term value, especially if you don’t keep the ‘why’ separated from what is probably going to be a verbose how.

But I would be happy to be shown wrong here.

Why make this about Claude? People are free to use any agentic coding LLM.

Documentation is firstly for yourself, secondly for your coworkers and/or users, and only last for AI. It is the art of writing and revising it that strengthens+questions+maintains one's understanding, so it doesn't make sense to have an AI write it.

There are at least eight top-level comments here saying that Claude reads documentation, but humans don't.

In aerospace related industries there is a culture of writing and reading of requirements.

I system engineered for a major US satellite TV provider, and just the specification that defined the protocol for transmitting guide data over the satellite was about 640 US letter pages when printed.

I've never had this problem.

The problem I have had is other developers expecting me to maintain documentation for their tools. To the point that they wage stupid inter office wars because they don't want to learn a command line utility with 20+ years of documentation itself.

Managers will document for employees. That’s maybe the better comparison.