Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Programmers will document for Claude, but not for each other

blog.plover.com

Post reply on HN
Print view View original

111–120 of 166 posts

Re: Programmers will document for Claude, but not for each other

#111

Post by vkou »

hennell wrote: post #90
ang_cire wrote: post #9

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.

I have a pretty decent readme on all projects, and a /docs folder for key areas that need specific instruction on complex ones. My boss was looking at them, but even the simple ones he was pointing claude at it and asked it to make a document explaining it. Then he'd send me the document and ask me to check if it was accurate. I added a line to the last page "this is an ai summary and may contain mistakes. Use the pr…

It's good that you're helping to pad your boss' CL and doc output count.

His OKR for IC contributions on top of his management responsibilities won't fill itself.

Re: Programmers will document for Claude, but not for each other

#113

Post by matheusmoreira »

kuboble wrote: post #27

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…

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.

Re: Programmers will document for Claude, but not for each other

#114

Post by waffletower »

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.

Re: Programmers will document for Claude, but not for each other

#116

Post by matheusmoreira »

skybrian wrote: post #84

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 u…

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.

Re: Programmers will document for Claude, but not for each other

#117

Post by AnimalMuppet »

digitallogic wrote: post #115

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.

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.

Re: Programmers will document for Claude, but not for each other

#118

Post by binaryturtle »

docheinestages wrote: post #89

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.

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)

Re: Programmers will document for Claude, but not for each other

#119

Post by matheusmoreira »

docheinestages wrote: post #89

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.

I simply added a documentation agent to my parallel code review skill. Automatically finds documentation drift.

Re: Programmers will document for Claude, but not for each other

#120

Post by Vaslo »

noufalibrahim wrote: post #18
ang_cire wrote: post #9

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.

Yup. Claude will rtfm. Most humans won't.

Because the manual usually sucks
Post reply on HN