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.

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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

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.

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.

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

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…

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.

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

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.

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.

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

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.

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.

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.

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.

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?

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

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.

Documenting for Claude: you put in the work to get what you want.

Seems pretty straightforward.

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

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

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.

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.

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.

Unstrutuced slop is no better at best, and much worse at worst.

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.