Maybe because the AI will actually read it?
Programmers will document for Claude, but not for each other
91–100 of 166 posts
Re: Programmers will document for Claude, but not for each other
#92Shocker, when something actually reads your documentation, you will write for that thing. When it clearly doesn’t, you don’t give a fuck.
Re: Programmers will document for Claude, but not for each other
#93We 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 developme…
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.
Isn’t what you are describing, a programming language? I‘m not sold on specs being everything you need to implement correctly.
Re: Programmers will document for Claude, but not for each other
#94What a weird title for an article about something almost entirely unrelated
Re: Programmers will document for Claude, but not for each other
#95Earlier quoted context omitted.
When someone asks me a question that is or should be documented, I like to ask where they looked for it (link or search query). * Sometimes, this prompt is enough for them to find the answer. * Sometimes, they tell me a spot that makes sense to them, and I make it have the answer. (Maybe just by adding a cross-reference.) * If they refuse to look at the docs, I can't help them.
The answer has always been “I asked Bob and Bob half remembered you worked in it once”, without any attempt to look for info, in my experience :(
When I get that, I just repeat the question "where did you look in the docs?", or just "go look at the docs now" if they're really dense. I can't help them until they have a better answer.
It takes a few tries before they internalize that they need to have a doc link before expecting my help. Once they do, I might take the next step to saying "here's the answer; can you update the docs so the next person doesn't have to ask?" And it might take a few tries before that sticks too. My goal is to eventually turn them into someone who evangelizes the docs themselves.
When I write peer reviews for my colleagues, I describe their attitude toward documentation. If that's "they refuse to open the docs, frequently wasting their colleagues' time", it's not gonna go well. If it's "they make nice doc edits after I ask them", a little better. If it's "they proactively maintain the documentation", better still.
Of course all this is for stuff that one could reasonably expect to be documented. Help thinking through a design problem or debugging their in-progress PR is generally a different situation.
Re: Programmers will document for Claude, but not for each other
#96Earlier quoted context omitted.
Yup. Claude will rtfm. Most humans won't.
If you tell it to. Otherwise you might get the classic "You're absolutely right – I made that up. Let me look at the documentation"
if you find yourself saying 'if you tell it to' a lot about LLMs that usually just says something about your prompting methods.
or, in other words , if you want the thing to always read the documentation then make that a strongly highlighted point both in pre-prompts, active prompts, and memory.
Re: Programmers will document for Claude, but not for each other
#97tl;dr
Re: Programmers will document for Claude, but not for each other
#98It’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!
Re: Programmers will document for Claude, but not for each other
#99I 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.
Re: Programmers will document for Claude, but not for each other
#100> 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 b…
no one expects humans to read CLAUDE.md
it's never been easier to catch up to the team guru