9 ms·

Programmers will document for Claude, but not for each other

187 points by surprisetalk 5mo ago

cyanydeez 5mo ago
sure, but those documents are generally just as useless because they're 70% complete, 10% indirect and 20% wrong. Unstrutuced slop is no better at best, and much worse at worst.
- grebc 5mo ago
  Slop in, slop out. The new GIGO?
- Traubenfuchs 5mo ago
  Ahh yes, the documentation for claude. When someone created a CLAUDE.md, then changed some stuff around and when I later had to touch that repository my claude was hallucinating classes, functions and architecture that was already long gone! I just deleted the CLAUDE.md, since I had no mood to "fix" it.
  - joebates 5mo ago
    Couldn't you have claude correct the CLAUDE.md?
    - cyanydeez 5mo ago
      Thats what "autoresearch" does, init?
- bachmeier 5mo ago
  > 70% complete, 10% indirect and 20% wrong I haven't had too much problem with information in summaries being wrong, but there have been times the LLM will miss the most important details. Then when you tell it, the response is "Nice catch!" or something like that.
  - cyanydeez 5mo ago
    normal human reading speed is 35 WPM. Here's what that looks like, assuming 1 word equals 1 token: https://mikeveerman.github.io/tokenspeed/?rate=35.7&mode=code https://mikeveerman.github.io/tokenspeed/?rate=35.7&mode=cod... When you say "you haven't had much problem" one can only assume you're _not actually reading the output_. In fact, like most things in modern times, one has to assume you arn't actually reading the output. You're skimming it; you're finding what makes sense and extrapolating that. This is the 70%. The problem with non-deterministic models is that the output can't be deterministically assessed. You're harboring a delusion that you're getting real good output. Most likely you're doing the baby extrapolation: you make it do a small, tightly scoped project and it's does 99% right. Just like a baby doubles in size in a year. Extrapolating, that baby will double again; but it doesnt. Your human compensation limits does not extrapolate to the size and knowledge that's fed into the model and the context it extrapolates.
  - ModernMech 5mo ago
    The key thing that makes a summary valuable is it retains the most important details while being shorter. Missing those details makes the summary wrong.
dude250711 5mo ago
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).
- redsocksfan45 5mo ago
  [dead]
- perching_aix 5mo ago
  > well parse for autocompletion, not actually "read", unless you are under AI-psychosis A cheese-grater Mac is not a door stop either, yet look at it go. Will people ever let go of being hung up on how exactly an LLM produces text, or do I really have to keep listening to this shit for the next several decades? As if being a program didn't already prohibit them from reading to begin with! Tell me how you don't think a plane should be characterized as "flying" unless one is in "avionics-psychosis" or something. Surely you can appreciate how this narrow requirement for avoiding anthropomorphism and metaphors is entirely performative, and that engaging in them is in no way a sign of any mental illness. And I get the performance aspect behind it, people wish to reject the metaphor to tear into the thing even that way. Or they come from a religious or spiritualistic background, and find the mere comparison insulting. But fuck it's so cringe. It's not news, and it's not insightful. Nobody who's ever had them shit out a page per second via like a dozen subagents, or utilized them being stateless and seed-bound, has any actual illusions about them being anything more than "just text generators". If they nevertheless assign intelligence, understanding, or similar traits to them, then clearly they simply don't agree with the anthropocentric philosophical insinuations performed. It's not some mistake or psychosis. Come on.
gonzalohm 5mo ago
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?
- hilariously 5mo ago
  eh, that seems like the least harmful part of this entire thing, we've had that for decades https://www.youtube.com/watch?v=urcL86UpqZc https://www.youtube.com/watch?v=urcL86UpqZc
- kolinko 5mo ago
  “Modern kids don’t program, they just play with frameworks” Well of course people adjust their harnesses, skills and whatnot - that is how programming looks like now. You don’t touch the code, you build a machine that builds the code instead. The question is how much people can produce this way. Me, personally, a ton - right now I feel I can do in a week what would take me a month-two. And I’ve had 20 years of experience in programming.
- hgoel 5mo ago
  That's just what the people that liked to put a lot of effort into customizing their IDEs or WMs have moved to.
- matheusmoreira 5mo ago
  Yes. I ran /insights on Claude Code and it said code review was my most requested activity. I turned it into a skill that autodiscovers the project's structure and launches a huge matrix of parallel critic agents, each focusing on one specific area of the codebase and a quality like correctness, maintainability, security, etc. Supports file system style journaling to deal with subscription usage limits and interruptions. Took maybe a few hours to fine tune this and then I applied it to all of my projects, and it's actually absurd how productive it is. This is basically an infinite GitHub issue generator. I run it and then start checking off the items in order to definitely improve the status quo. Review again, fix again. Just loop this until zero issues found. The only question is whether to fix the issues myself or tell Claude to do it. I still do it myself in the projects I really care about.
freddieRidell 5mo ago
yeah, because claude will actually read the docs
ang_cire 5mo ago
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.
- hilariously 5mo ago
  Right, this seems like an obvious conclusion - what is the outcome of the person writing the docs in either case: 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.
  - deleted 5mo ago
    [deleted]
  - rufo 5mo ago
    re: #2: I'm in this description, and I am anguished by how much I do not like it. (reference: https://knowyourmeme.com/memes/im-in-this-photo-and-i-dont-like-it https://knowyourmeme.com/memes/im-in-this-photo-and-i-dont-l...)
    - hilariously 5mo ago
      It's bad for us, but I imagine the tech writers feelings are even darker. They spent years being demonstrating how important good docs were, nobody in management cared, they were mostly laid off and discarded before there was even a credible replacement available.
    - tstrimple 5mo ago
      One of the clients I’m consulting with has one of the best cloud onboarding docs I’ve ever seen. Lays out exactly the services supported. Who does what pieces. What is self service. They break out latency differences between the cloud environments and on-premises. A serious amount of good work that’s incredibly useful working within their system. I use it frequently. Their head of cloud engineering has a permanent “away” message on Teams pleading with people to check the cloud docs first instead of just asking him directly. I would be frustrated too.
Pxtl 5mo ago
I've been noticing that too. "Hey, the normal documentation for our software of a crude API list describing what each command is and each of its parameters isn't good enough for the AI. We need to provide the AI with instructions on how to use the software to solve common problems" Uh, you needed to do that for humans too. You just didn't. There's a reason everybody scrolls to the bottom of man pages ASAP.
redsocksfan45 5mo ago
[dead]
jfyi 5mo ago
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.
jerf 5mo ago
Yes, I've already "abused" this a couple of times to get some docs written that we had needed for years but hadn't been written. All kinds of docs; code documentation, deployment documentation, overview documentation, architecture documentation. APIs that we kicked around as being useful for years are now actually on track to be written because we can't integrate non-existent APIs into MCP servers or skills. On the one hand, I also feel like "come on, couldn't we have done this earlier?" On the other hand... the costs of the docs have decreased. Simply firing a frontier model at your code base doesn't always produce perfect docs but it's a heck of a good start. I do recommend some tuning in the request, e.g. I like to explicitly ask the AI to document data flow rather than the usual list of "here's this component, here's this component, here's this component", but it's pretty easy. And the utility of docs is now much higher. I really just recently moved into the classical "architect" role and in some ways I'm glad it wasn't much sooner, because my GenX cynicism tells me that nobody ever reads the architecture docs. OK, OK, sure, technically nobody is a bit too strong. Sometimes, some particularly intrepid or conscientious souls surely read them at some point. But from my own experience I could count on being able to hand out API docs, structure docs, flow docs, and their primary utility was that when someone tried to deflect responsibility with "but but but they didn't provide any docs" they couldn't, because I had. People eventually learned to stop doing that because I always provided the docs because I saw that coming. And they made a great background on the shared screen as I had to walk someone through the entire thing in a meeting anyhow. They were more a really specialized meeting transcript than something I could provide in advance and expect much out of. But now, if nothing else, AI will read the documentation. I can tell people to pull it in, and while it doesn't mean all my problems go away, there is now a much cleaner path for me from "writing an architecture doc" -> "lines of code in somebody's repo" than there was pre-AI. My architecture docs are now somebody else's prompts. The utility of this sort of documentation skyrockets compared to the old days. So, when the costs decrease and the benefits increase, it isn't a surprise that suddenly, it's easier to get some of these things done that we "knew" we needed for a long time, but now with the new cost/benefit ratio can cross the action threshold.
jimberlage 5mo ago
Managers will document for employees. That’s maybe the better comparison.
loglog 5mo ago
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.
- SoftTalker 5mo ago
  Employees get paid either way, so weirdly that makes it less motivating. Costs aren't lower if you put more work into writing a good spec. When you're paying piecework style, suddenly the work needed to write a good spec has a bottom-line payoff.
phplovesong 5mo ago
I have large doc file from a feature and everytime i tell claude to do something (read it) it consumes a shitton of tokens. Better to have small focused facts for ai instead.
empath75 5mo ago
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.
kuboble 5mo ago
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.
- frizlab 5mo ago
  But the critique is good! I strive for feedback when I write docs. Usually they are just ignored though.
- matheusmoreira 5mo ago
  I've been rewriting the documentation Claude outputs before committing it. Partly because I want to understand what was written, but also because I want the writing to match my own writing style and voice instead of the usual overly verbose LLM output. Now I'm wondering if I'm just making the documentation worse for the one coding buddy I've got that reads it.
raincole 5mo ago
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.
maxpow3r 5mo ago
I get claude to write a context.md for any github project i'm working on. It helps keep my context up to date, or else claude keeps telling me to build things I've already built.
samuelknight 5mo ago
I learned a long time ago to avoid writing long emails because people don't read them. LLMs are quite the opposite, and will have 'attention' for every word you prompt it with.
- duskdozer 5mo ago
  Ah, I had that realization too. Then I started writing short emails and they still didn't read them.
dfxm12 5mo ago
If you have Claude write down notes, check them into the repo when you're done. It probably can't hurt and it might help. LOL. It didn't even cross the author's mind to consider reading the notes himself to decide if they make sense. AI is sending us down a path of anti-social behavior. It will be bad for us, of course, but AI is only as good as it is because it was able to be trained on info from github, stack overflow, etc. Without socializing interesting info, humans and AI will both suffer.
brap 5mo ago
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…
- addedGone 5mo ago
  most issues in my company are just automatically solved now, we are at a point where the issue is just writing the issue (that's what requires mental effort).
jillesvangurp 5mo ago
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.
seanwilson 5mo ago
> 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.
- readme 5mo ago
  no one expects humans to read CLAUDE.md it's never been easier to catch up to the team guru
pixel_popping 5mo ago
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.
- dbvn 5mo ago
  [flagged]
  - pixel_popping 5mo ago
    What's funny?
arjie 5mo ago
Truth be told, I wrote docs for other programmers but now I have Claude Code write docs for itself but if you looked you might conclude that I wrote docs for Claude.
cush 5mo ago
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.
kittikitti 5mo ago
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?
- triMichael 5mo ago
  I'm one of those developers, and I think it makes sense to write documentation for Claude and I have no issues with that. The point of self-documenting code isn't to get rid of the documentation. Instead, it's to integrate it into the code. This fixes the two biggest problems with documentation. First, that the code will often be updated and documentation left behind, making it useless. And second, that English and code are intertwined in the same document, making you constantly switch mental contexts of how you are reading. So no, I don't consider developers who write documentation to be inferior. If anything, I value documentation even more, and the purpose of self-documenting code is to make the documentation better, not get rid of it. With Claude, the documentation you make for Claude is just fine as it doesn't run into any of the above two problems. The documentation isn't being left behind, because you add to it instead of the code. And it's not intertwined with code, because you are just writing English for Claude, you are not writing code in-between.
cosmicriver 5mo ago
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.
ElevenLathe 5mo ago
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.
sumitkumar 5mo ago
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.
- rootsudo 5mo ago
  This is so true. I hate it. I document the same way for myself as I do with claude/codex and it's great it wasn't to much of a difference to be more verbose outside maximizing tokens.
manmal 5mo ago
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.
- chasd00 5mo ago
  I get the feeling specifications documents are going to become the hot new programming language. I suspect, over time, we'll see special syntax and semantic conventions get published for specifications docs that result in the best chance for a coding agent to get the implementation right the first time and with minimal tokens.
  - manmal 5mo ago
    Isn’t what you are describing, a programming language? I‘m not sold on specs being everything you need to implement correctly.
nrds 5mo ago
Wait until you realize that MCPs are just the APIs that we've failed to write before, and skills are just the documentation and simple CLIs we've failed to write before
saidnooneever 5mo ago
unlike programmers, claude understands programmers.
- tomjakubowski 5mo ago
  You don't need a theory of mind to effectively manage or collaborate with a chatbot. You do for other humans.
dionian 5mo ago
But Claude will actually read it
wolttam 5mo ago
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.
VulgarExigency 5mo ago
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.
- transitorykris 5mo ago
  I came to this realization after seeing developers churn out 30 minute long reads of slop documentation. It's for the agent, and the human interface to it is through the agent. Over the last week the plans that Claude has been writing for issues have been largely a single massive unreadable paragraph of awkward sentences, but it's working, the implementations from it have been solid.
  - infinite_spin 5mo ago
    the key to avoiding slop in this context is to have it write inline documentation (e.g. jsdoc), so that you can quickly review if it matches the required implementation/interface
OutOfHere 5mo ago
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.
fga_qwrh 5mo ago
Another blogger goes down. Of course programmers have documented important software for each other. Claude emits garbage, so documentation will be garbage as well. It doesn't matter, because everything will be rewritten and tokenmaxxed anyway. In other words, the blogger now has a job where Claude is foisted upon him and he toes the line.
bdcravens 5mo ago
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.
skybrian 5mo ago
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.
- matheusmoreira 5mo ago
  The design document and plan are just there to ensure the agent has all the context and instructions to implement it correctly. After it's done, I ask the agent to salvage any useful information into proper documentation and delete the implementation files.
DuduZhvania 5mo ago
[flagged]
docheinestages 5mo ago
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.
- binaryturtle 5mo ago
  I recall, back in the AmigaOS days, we kept the documentation inline with the code. E.g. you had your exported API function in a shared library code's .c file, with the documentation right above it sitting in a special formatted comment. Easily kept in sync (code wasn't that convoluted back then either.) Afterwards, during the build phase, the documentation (for other developers) was extracted on-the-fly. There was a fixed format/style and the documentation was compact and actually useful too. (aka "autodocs", for those who remember the term)
- matheusmoreira 5mo ago
  I simply added a documentation agent to my parallel code review skill. Automatically finds documentation drift.
  - docheinestages 5mo ago
    That could work, but there's still the chance that things could diverge if multiple people are working on a project and not everyone is as diligent as you. With LLM context windows continuously growing, agents should be able to scan the whole repository and even relevant repositories on the fly, provided they contain the truth and only what's necessary (i.e. minimal commentary).
ExoticPearTree 5mo ago
Maybe because the AI will actually read it?
deadbabe 5mo ago
Shocker, when something actually reads your documentation, you will write for that thing. When it clearly doesn’t, you don’t give a fuck.
sceptic123 5mo ago
What a weird title for an article about something almost entirely unrelated
mjd 5mo ago
tl;dr
lowbloodsugar 5mo ago
It’s fun to watch others on their journey. Young grasshopper here has had the first revelation about documentation with AI but also about humans. Good work! Keep thinking!
readme 5mo ago
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.
- jihadjihad 5mo ago
  Username checks out?
nyrikki 5mo ago
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.
beachWholesaleS 5mo ago
TBH self-documenting code works for other developers. Documents and documents of context is required for Claude. It's covering a previously missing gap!
maxothex 5mo ago
[flagged]
waffletower 5mo ago
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.
digitallogic 5mo ago
Document for other developers: you put in the work for someone else to get what they want. Documenting for Claude: you put in the work to get what you want. Seems pretty straightforward.
- AnimalMuppet 5mo ago
  To me, it seems also that the delta between "how it works with the documentation" and "how it works without the documentation" is higher for Claude than for coworkers. That is, the documentation is more required with Claude.
__MatrixMan__ 5mo ago
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.
- grumpymuppet 5mo ago
  I bet a huge amount of that is on your head, or if it is factual, a function of a toxic work culture where people are primarily incentivized to "outperform one another" rather than arrive at collaborative solutions. The wealthy/owner class once again consume all of us -- here through AI -- because we cannot agree to work together.
  - vitally3643 5mo ago
    No. It is a well established fact that the majority of users will not read documentation of any kind. This is not a new observation, it's been a meme in developer circles from the first day computers showed up in the workplace. You can step off your high horse now.
    - satvikpendem 5mo ago
      It's not just docs too, it seems to be some general phenomenon that users don't read most anything on screen. This is from almost 20 years ago [0] and the original stretches back almost 30 years now [1]. [0] https://www.nngroup.com/articles/how-little-do-users-read/ https://www.nngroup.com/articles/how-little-do-users-read/ [1] https://www.nngroup.com/articles/how-users-read-on-the-web/ https://www.nngroup.com/articles/how-users-read-on-the-web/
    - socalgal2 5mo ago
      In my defense. (1) I can't find the docs (2) I can't find the relevant docs (3) after having read several irrelevant docs they still don't answer my question but the question I need answering isn't actually in the docs.
sowbug 5mo ago
There are at least eight top-level comments here saying that Claude reads documentation, but humans don't.
thisisit 5mo ago
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.
zahlman 5mo ago
> I'm a little slow so it took me until this week to think of a better version of this: at the end of the project I now ask Claude to write up from scratch a detailed but high-level explanation of what problem we were solving and what changes we made, and I commit that. Not just running notes, but a structured overview of the whole thing. I feel like the right place for this information is in the Git history itself. If it doesn't logically fit in commit messages, then maybe on an annotated tag or something? > Claude's new document had an identical section at the end. Oops! Fortunately, by the time I saw it, it was true, so I didn't have to delete it. I had Claude add a sentence to CLAUDE.md to tell it not to do this again. ... Is this actually easier than editing it yourself?
- p1anecrazy 5mo ago
  I understand the author wants to add it every time as a signature, and having claude do it doesn‘t fulfill the purpose
  - zahlman 5mo ago
    I meant: why tell Claude to edit CLAUDE.md to add the "don't add a signature" rule, instead of just writing a "don't add a signature" rule into CLAUDE.md directly? The necessary rule can't be much longer than the prompt generating it, surely.
erelong 5mo ago
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
nunez 5mo ago
Why not just commit your conversation history? You can run gitleaks again it to check for secrets, or you can just ask Claude to sanitize it if you trust it.
nunez 5mo ago
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.)
- pixl97 5mo ago
  > most of that super detailed documentation is AI-generated, so there be dragons. You can somewhat automatically test this by having some other AI agent/model read your docs and successfully implement it.
scelerat 5mo ago
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.
GarnetFloride 5mo ago
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.
Balooga 5mo ago
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.
casey2 5mo ago
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 https://developers.openalex.org/guides/llm-quick-reference
ares623 5mo ago
What I see in this thread is that WE HATE EACH OTHER SO FUCKING MUCH that we would rather see the world burn than spend another second interacting with our inferior coworkers. Only _my_ time and effort is important.
dsmurrell 5mo ago
It's because Claude RTFM.
MantisShrimp90 5mo ago
I mean yea my take is that there's basically nothing that claude could benefit from that humans wont. So I see no reason to make claude-specific docs. With that said, yes, the difference is I KNOW claude will read my docs, especially if I shove it into the context and therefore, I KNOW I'm getting ROI on that work. As someone who has written docs for years I have spent too many hours writing docs that my colleagues proceed to just ignore and ask me to explain verbally. Its a culture thing if people don't have a natural instinct to read docs and a culture of documentation and asking others to read the docs INSTEAD of bothering the human. Also, there may be something to the theory that people don't learn well from docs as tutorial. I find 10x faster return when I make a video for people or tutor them through something rather than sending them a link and asking them to read it. Often this is because good docs are disciplined and try to answer the one question they were asked. Which is great, untill you realize most are missing necessary background so now you're in a bind. Do you document foundations that are covered in other places? Or do you cover them in your own words making 10x more work for questionable value? Its not an easy question
cadamsdotcom 5mo ago
People are selfish. Document for agent: it makes less dumb mistakes. I go faster Document for teammates: they might go faster and get stack ranked above me Document for future engineers: does it impact my salary to skip that? No? Ok.
sermakarevich 5mo ago
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
coldtea 5mo ago
>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").
swordsith 5mo ago
programmers will get the dark-light mode preference from my browser, and still choose to blind me.

187 points by surprisetalk 5mo ago

sure, but those documents are generally just as useless because they're 70% complete, 10% indirect and 20% wrong. Unstrutuced slop is no better at best, and much worse at worst.

grebc 5mo ago
Slop in, slop out. The new GIGO?
Traubenfuchs 5mo ago
Ahh yes, the documentation for claude. When someone created a CLAUDE.md, then changed some stuff around and when I later had to touch that repository my claude was hallucinating classes, functions and architecture that was already long gone! I just deleted the CLAUDE.md, since I had no mood to "fix" it.
- joebates 5mo ago
  Couldn't you have claude correct the CLAUDE.md?
  - cyanydeez 5mo ago
    Thats what "autoresearch" does, init?
bachmeier 5mo ago
> 70% complete, 10% indirect and 20% wrong I haven't had too much problem with information in summaries being wrong, but there have been times the LLM will miss the most important details. Then when you tell it, the response is "Nice catch!" or something like that.
- cyanydeez 5mo ago
  normal human reading speed is 35 WPM. Here's what that looks like, assuming 1 word equals 1 token: https://mikeveerman.github.io/tokenspeed/?rate=35.7&mode=code https://mikeveerman.github.io/tokenspeed/?rate=35.7&mode=cod... When you say "you haven't had much problem" one can only assume you're _not actually reading the output_. In fact, like most things in modern times, one has to assume you arn't actually reading the output. You're skimming it; you're finding what makes sense and extrapolating that. This is the 70%. The problem with non-deterministic models is that the output can't be deterministically assessed. You're harboring a delusion that you're getting real good output. Most likely you're doing the baby extrapolation: you make it do a small, tightly scoped project and it's does 99% right. Just like a baby doubles in size in a year. Extrapolating, that baby will double again; but it doesnt. Your human compensation limits does not extrapolate to the size and knowledge that's fed into the model and the context it extrapolates.
- ModernMech 5mo ago
  The key thing that makes a summary valuable is it retains the most important details while being shorter. Missing those details makes the summary wrong.

dude250711 5mo ago

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).

redsocksfan45 5mo ago
[dead]
perching_aix 5mo ago
> well parse for autocompletion, not actually "read", unless you are under AI-psychosis A cheese-grater Mac is not a door stop either, yet look at it go. Will people ever let go of being hung up on how exactly an LLM produces text, or do I really have to keep listening to this shit for the next several decades? As if being a program didn't already prohibit them from reading to begin with! Tell me how you don't think a plane should be characterized as "flying" unless one is in "avionics-psychosis" or something. Surely you can appreciate how this narrow requirement for avoiding anthropomorphism and metaphors is entirely performative, and that engaging in them is in no way a sign of any mental illness. And I get the performance aspect behind it, people wish to reject the metaphor to tear into the thing even that way. Or they come from a religious or spiritualistic background, and find the mere comparison insulting. But fuck it's so cringe. It's not news, and it's not insightful. Nobody who's ever had them shit out a page per second via like a dozen subagents, or utilized them being stateless and seed-bound, has any actual illusions about them being anything more than "just text generators". If they nevertheless assign intelligence, understanding, or similar traits to them, then clearly they simply don't agree with the anthropocentric philosophical insinuations performed. It's not some mistake or psychosis. Come on.

gonzalohm 5mo ago

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?

hilariously 5mo ago
eh, that seems like the least harmful part of this entire thing, we've had that for decades https://www.youtube.com/watch?v=urcL86UpqZc https://www.youtube.com/watch?v=urcL86UpqZc
kolinko 5mo ago
“Modern kids don’t program, they just play with frameworks” Well of course people adjust their harnesses, skills and whatnot - that is how programming looks like now. You don’t touch the code, you build a machine that builds the code instead. The question is how much people can produce this way. Me, personally, a ton - right now I feel I can do in a week what would take me a month-two. And I’ve had 20 years of experience in programming.
hgoel 5mo ago
That's just what the people that liked to put a lot of effort into customizing their IDEs or WMs have moved to.
matheusmoreira 5mo ago
Yes. I ran /insights on Claude Code and it said code review was my most requested activity. I turned it into a skill that autodiscovers the project's structure and launches a huge matrix of parallel critic agents, each focusing on one specific area of the codebase and a quality like correctness, maintainability, security, etc. Supports file system style journaling to deal with subscription usage limits and interruptions. Took maybe a few hours to fine tune this and then I applied it to all of my projects, and it's actually absurd how productive it is. This is basically an infinite GitHub issue generator. I run it and then start checking off the items in order to definitely improve the status quo. Review again, fix again. Just loop this until zero issues found. The only question is whether to fix the issues myself or tell Claude to do it. I still do it myself in the projects I really care about.

freddieRidell 5mo ago

yeah, because claude will actually read the docs

ang_cire 5mo ago

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.

hilariously 5mo ago
Right, this seems like an obvious conclusion - what is the outcome of the person writing the docs in either case: 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.
- deleted 5mo ago
  [deleted]
- rufo 5mo ago
  re: #2: I'm in this description, and I am anguished by how much I do not like it. (reference: https://knowyourmeme.com/memes/im-in-this-photo-and-i-dont-like-it https://knowyourmeme.com/memes/im-in-this-photo-and-i-dont-l...)
  - hilariously 5mo ago
    It's bad for us, but I imagine the tech writers feelings are even darker. They spent years being demonstrating how important good docs were, nobody in management cared, they were mostly laid off and discarded before there was even a credible replacement available.
  - tstrimple 5mo ago
    One of the clients I’m consulting with has one of the best cloud onboarding docs I’ve ever seen. Lays out exactly the services supported. Who does what pieces. What is self service. They break out latency differences between the cloud environments and on-premises. A serious amount of good work that’s incredibly useful working within their system. I use it frequently. Their head of cloud engineering has a permanent “away” message on Teams pleading with people to check the cloud docs first instead of just asking him directly. I would be frustrated too.

Pxtl 5mo ago

I've been noticing that too. "Hey, the normal documentation for our software of a crude API list describing what each command is and each of its parameters isn't good enough for the AI. We need to provide the AI with instructions on how to use the software to solve common problems" Uh, you needed to do that for humans too. You just didn't. There's a reason everybody scrolls to the bottom of man pages ASAP.

redsocksfan45 5mo ago

[dead]

jfyi 5mo ago

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.

jerf 5mo ago

Yes, I've already "abused" this a couple of times to get some docs written that we had needed for years but hadn't been written. All kinds of docs; code documentation, deployment documentation, overview documentation, architecture documentation. APIs that we kicked around as being useful for years are now actually on track to be written because we can't integrate non-existent APIs into MCP servers or skills. On the one hand, I also feel like "come on, couldn't we have done this earlier?" On the other hand... the costs of the docs have decreased. Simply firing a frontier model at your code base doesn't always produce perfect docs but it's a heck of a good start. I do recommend some tuning in the request, e.g. I like to explicitly ask the AI to document data flow rather than the usual list of "here's this component, here's this component, here's this component", but it's pretty easy. And the utility of docs is now much higher. I really just recently moved into the classical "architect" role and in some ways I'm glad it wasn't much sooner, because my GenX cynicism tells me that nobody ever reads the architecture docs. OK, OK, sure, technically nobody is a bit too strong. Sometimes, some particularly intrepid or conscientious souls surely read them at some point. But from my own experience I could count on being able to hand out API docs, structure docs, flow docs, and their primary utility was that when someone tried to deflect responsibility with "but but but they didn't provide any docs" they couldn't, because I had. People eventually learned to stop doing that because I always provided the docs because I saw that coming. And they made a great background on the shared screen as I had to walk someone through the entire thing in a meeting anyhow. They were more a really specialized meeting transcript than something I could provide in advance and expect much out of. But now, if nothing else, AI will read the documentation. I can tell people to pull it in, and while it doesn't mean all my problems go away, there is now a much cleaner path for me from "writing an architecture doc" -> "lines of code in somebody's repo" than there was pre-AI. My architecture docs are now somebody else's prompts. The utility of this sort of documentation skyrockets compared to the old days. So, when the costs decrease and the benefits increase, it isn't a surprise that suddenly, it's easier to get some of these things done that we "knew" we needed for a long time, but now with the new cost/benefit ratio can cross the action threshold.

jimberlage 5mo ago

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

loglog 5mo ago

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.

SoftTalker 5mo ago
Employees get paid either way, so weirdly that makes it less motivating. Costs aren't lower if you put more work into writing a good spec. When you're paying piecework style, suddenly the work needed to write a good spec has a bottom-line payoff.

phplovesong 5mo ago

I have large doc file from a feature and everytime i tell claude to do something (read it) it consumes a shitton of tokens. Better to have small focused facts for ai instead.

empath75 5mo ago

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.

kuboble 5mo ago

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.

frizlab 5mo ago
But the critique is good! I strive for feedback when I write docs. Usually they are just ignored though.
matheusmoreira 5mo ago
I've been rewriting the documentation Claude outputs before committing it. Partly because I want to understand what was written, but also because I want the writing to match my own writing style and voice instead of the usual overly verbose LLM output. Now I'm wondering if I'm just making the documentation worse for the one coding buddy I've got that reads it.

raincole 5mo ago

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.

maxpow3r 5mo ago

I get claude to write a context.md for any github project i'm working on. It helps keep my context up to date, or else claude keeps telling me to build things I've already built.

samuelknight 5mo ago

I learned a long time ago to avoid writing long emails because people don't read them. LLMs are quite the opposite, and will have 'attention' for every word you prompt it with.

duskdozer 5mo ago
Ah, I had that realization too. Then I started writing short emails and they still didn't read them.

dfxm12 5mo ago

If you have Claude write down notes, check them into the repo when you're done. It probably can't hurt and it might help. LOL. It didn't even cross the author's mind to consider reading the notes himself to decide if they make sense. AI is sending us down a path of anti-social behavior. It will be bad for us, of course, but AI is only as good as it is because it was able to be trained on info from github, stack overflow, etc. Without socializing interesting info, humans and AI will both suffer.

brap 5mo ago

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…

addedGone 5mo ago
most issues in my company are just automatically solved now, we are at a point where the issue is just writing the issue (that's what requires mental effort).

jillesvangurp 5mo ago

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.

seanwilson 5mo ago

> 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.

readme 5mo ago
no one expects humans to read CLAUDE.md it's never been easier to catch up to the team guru

pixel_popping 5mo ago

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.

dbvn 5mo ago
[flagged]
- pixel_popping 5mo ago
  What's funny?

arjie 5mo ago

Truth be told, I wrote docs for other programmers but now I have Claude Code write docs for itself but if you looked you might conclude that I wrote docs for Claude.

cush 5mo ago

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.

kittikitti 5mo ago

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?

triMichael 5mo ago
I'm one of those developers, and I think it makes sense to write documentation for Claude and I have no issues with that. The point of self-documenting code isn't to get rid of the documentation. Instead, it's to integrate it into the code. This fixes the two biggest problems with documentation. First, that the code will often be updated and documentation left behind, making it useless. And second, that English and code are intertwined in the same document, making you constantly switch mental contexts of how you are reading. So no, I don't consider developers who write documentation to be inferior. If anything, I value documentation even more, and the purpose of self-documenting code is to make the documentation better, not get rid of it. With Claude, the documentation you make for Claude is just fine as it doesn't run into any of the above two problems. The documentation isn't being left behind, because you add to it instead of the code. And it's not intertwined with code, because you are just writing English for Claude, you are not writing code in-between.

cosmicriver 5mo ago

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.

ElevenLathe 5mo ago

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.

sumitkumar 5mo ago

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.

rootsudo 5mo ago
This is so true. I hate it. I document the same way for myself as I do with claude/codex and it's great it wasn't to much of a difference to be more verbose outside maximizing tokens.

manmal 5mo ago

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.

chasd00 5mo ago
I get the feeling specifications documents are going to become the hot new programming language. I suspect, over time, we'll see special syntax and semantic conventions get published for specifications docs that result in the best chance for a coding agent to get the implementation right the first time and with minimal tokens.
- manmal 5mo ago
  Isn’t what you are describing, a programming language? I‘m not sold on specs being everything you need to implement correctly.

nrds 5mo ago

Wait until you realize that MCPs are just the APIs that we've failed to write before, and skills are just the documentation and simple CLIs we've failed to write before

saidnooneever 5mo ago

unlike programmers, claude understands programmers.

tomjakubowski 5mo ago
You don't need a theory of mind to effectively manage or collaborate with a chatbot. You do for other humans.

dionian 5mo ago

But Claude will actually read it

wolttam 5mo ago

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.

VulgarExigency 5mo ago

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.

transitorykris 5mo ago
I came to this realization after seeing developers churn out 30 minute long reads of slop documentation. It's for the agent, and the human interface to it is through the agent. Over the last week the plans that Claude has been writing for issues have been largely a single massive unreadable paragraph of awkward sentences, but it's working, the implementations from it have been solid.
- infinite_spin 5mo ago
  the key to avoiding slop in this context is to have it write inline documentation (e.g. jsdoc), so that you can quickly review if it matches the required implementation/interface

OutOfHere 5mo ago

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.

fga_qwrh 5mo ago

Another blogger goes down. Of course programmers have documented important software for each other. Claude emits garbage, so documentation will be garbage as well. It doesn't matter, because everything will be rewritten and tokenmaxxed anyway. In other words, the blogger now has a job where Claude is foisted upon him and he toes the line.

bdcravens 5mo ago

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.

skybrian 5mo ago

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.

matheusmoreira 5mo ago
The design document and plan are just there to ensure the agent has all the context and instructions to implement it correctly. After it's done, I ask the agent to salvage any useful information into proper documentation and delete the implementation files.

DuduZhvania 5mo ago

[flagged]

docheinestages 5mo ago

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.

binaryturtle 5mo ago
I recall, back in the AmigaOS days, we kept the documentation inline with the code. E.g. you had your exported API function in a shared library code's .c file, with the documentation right above it sitting in a special formatted comment. Easily kept in sync (code wasn't that convoluted back then either.) Afterwards, during the build phase, the documentation (for other developers) was extracted on-the-fly. There was a fixed format/style and the documentation was compact and actually useful too. (aka "autodocs", for those who remember the term)
matheusmoreira 5mo ago
I simply added a documentation agent to my parallel code review skill. Automatically finds documentation drift.
- docheinestages 5mo ago
  That could work, but there's still the chance that things could diverge if multiple people are working on a project and not everyone is as diligent as you. With LLM context windows continuously growing, agents should be able to scan the whole repository and even relevant repositories on the fly, provided they contain the truth and only what's necessary (i.e. minimal commentary).

ExoticPearTree 5mo ago

Maybe because the AI will actually read it?

deadbabe 5mo ago

Shocker, when something actually reads your documentation, you will write for that thing. When it clearly doesn’t, you don’t give a fuck.

sceptic123 5mo ago

What a weird title for an article about something almost entirely unrelated

mjd 5mo ago

tl;dr

lowbloodsugar 5mo ago

It’s fun to watch others on their journey. Young grasshopper here has had the first revelation about documentation with AI but also about humans. Good work! Keep thinking!

readme 5mo ago

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.

jihadjihad 5mo ago
Username checks out?

nyrikki 5mo ago

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.

beachWholesaleS 5mo ago

TBH self-documenting code works for other developers. Documents and documents of context is required for Claude. It's covering a previously missing gap!

maxothex 5mo ago

[flagged]

waffletower 5mo ago

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.

digitallogic 5mo ago

Document for other developers: you put in the work for someone else to get what they want. Documenting for Claude: you put in the work to get what you want. Seems pretty straightforward.

AnimalMuppet 5mo ago
To me, it seems also that the delta between "how it works with the documentation" and "how it works without the documentation" is higher for Claude than for coworkers. That is, the documentation is more required with Claude.

__MatrixMan__ 5mo ago

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.

grumpymuppet 5mo ago
I bet a huge amount of that is on your head, or if it is factual, a function of a toxic work culture where people are primarily incentivized to "outperform one another" rather than arrive at collaborative solutions. The wealthy/owner class once again consume all of us -- here through AI -- because we cannot agree to work together.
- vitally3643 5mo ago
  No. It is a well established fact that the majority of users will not read documentation of any kind. This is not a new observation, it's been a meme in developer circles from the first day computers showed up in the workplace. You can step off your high horse now.
  - satvikpendem 5mo ago
    It's not just docs too, it seems to be some general phenomenon that users don't read most anything on screen. This is from almost 20 years ago [0] and the original stretches back almost 30 years now [1]. [0] https://www.nngroup.com/articles/how-little-do-users-read/ https://www.nngroup.com/articles/how-little-do-users-read/ [1] https://www.nngroup.com/articles/how-users-read-on-the-web/ https://www.nngroup.com/articles/how-users-read-on-the-web/
  - socalgal2 5mo ago
    In my defense. (1) I can't find the docs (2) I can't find the relevant docs (3) after having read several irrelevant docs they still don't answer my question but the question I need answering isn't actually in the docs.

sowbug 5mo ago

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

thisisit 5mo ago

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.

zahlman 5mo ago

> I'm a little slow so it took me until this week to think of a better version of this: at the end of the project I now ask Claude to write up from scratch a detailed but high-level explanation of what problem we were solving and what changes we made, and I commit that. Not just running notes, but a structured overview of the whole thing. I feel like the right place for this information is in the Git history itself. If it doesn't logically fit in commit messages, then maybe on an annotated tag or something? > Claude's new document had an identical section at the end. Oops! Fortunately, by the time I saw it, it was true, so I didn't have to delete it. I had Claude add a sentence to CLAUDE.md to tell it not to do this again. ... Is this actually easier than editing it yourself?

p1anecrazy 5mo ago
I understand the author wants to add it every time as a signature, and having claude do it doesn‘t fulfill the purpose
- zahlman 5mo ago
  I meant: why tell Claude to edit CLAUDE.md to add the "don't add a signature" rule, instead of just writing a "don't add a signature" rule into CLAUDE.md directly? The necessary rule can't be much longer than the prompt generating it, surely.

erelong 5mo ago

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

nunez 5mo ago

Why not just commit your conversation history? You can run gitleaks again it to check for secrets, or you can just ask Claude to sanitize it if you trust it.

nunez 5mo ago

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.)

pixl97 5mo ago
> most of that super detailed documentation is AI-generated, so there be dragons. You can somewhat automatically test this by having some other AI agent/model read your docs and successfully implement it.

scelerat 5mo ago

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.

GarnetFloride 5mo ago

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.

Balooga 5mo ago

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.

casey2 5mo ago

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 https://developers.openalex.org/guides/llm-quick-reference

ares623 5mo ago

What I see in this thread is that WE HATE EACH OTHER SO FUCKING MUCH that we would rather see the world burn than spend another second interacting with our inferior coworkers. Only _my_ time and effort is important.

dsmurrell 5mo ago

It's because Claude RTFM.

MantisShrimp90 5mo ago

I mean yea my take is that there's basically nothing that claude could benefit from that humans wont. So I see no reason to make claude-specific docs. With that said, yes, the difference is I KNOW claude will read my docs, especially if I shove it into the context and therefore, I KNOW I'm getting ROI on that work. As someone who has written docs for years I have spent too many hours writing docs that my colleagues proceed to just ignore and ask me to explain verbally. Its a culture thing if people don't have a natural instinct to read docs and a culture of documentation and asking others to read the docs INSTEAD of bothering the human. Also, there may be something to the theory that people don't learn well from docs as tutorial. I find 10x faster return when I make a video for people or tutor them through something rather than sending them a link and asking them to read it. Often this is because good docs are disciplined and try to answer the one question they were asked. Which is great, untill you realize most are missing necessary background so now you're in a bind. Do you document foundations that are covered in other places? Or do you cover them in your own words making 10x more work for questionable value? Its not an easy question

cadamsdotcom 5mo ago

People are selfish. Document for agent: it makes less dumb mistakes. I go faster Document for teammates: they might go faster and get stack ranked above me Document for future engineers: does it impact my salary to skip that? No? Ok.

sermakarevich 5mo ago

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

coldtea 5mo ago

>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").

swordsith 5mo ago

programmers will get the dark-light mode preference from my browser, and still choose to blind me.