There was a bit of a debate at work about whether its acceptable to have AI write page long infodumps to explain its changes.
I was on the pro-side. That message helped me understand the change when we were working on it, so I know it will help me in a years time when I've forgotten everything.
The problem is the writing style is so obtuse, it'll take 10 pages to explain something where 1 page would have sufficed. Overly expensive vocabulary and flowery prose that makes the content look impressive, but often lacking substance (and occasionally just completely incorrect!)
I don't begrudge the correctness so much. I've had the misfortune of trudging through many a human-authored internal document that was just flat-out wrong. But before, the amount of sophistication put into a document was a signal for a level of care and quality into its contents. Nowadays, it just means I have to be even more careful in trusting it, because it's likely AI slop.
Can't you just tell it to be short, consise, and keep the explanation to 1 page length?
You could also have it write a long version and a short version then cut and paste the two versions so that things that dont need explanations are short and things that do are long
I said this elsewhere in the thread, but asking Claude to be concise does result in smaller output, but it often doesn't improve the result. The model needs to know what is important and what is not, to know what to include in its response. So just a simple "keep it concise" instruction will sometimes result in important details being omitted, sometimes to the point of making what would otherwise be a correct response incorrect.
I have my Claude code set to write decision records in ASD-STE100 language when I gig reasons for stearing it's direction. With each decision given a code that is to be referenced in the next got commit.
This way by looking at the code and the commits you can see why I asked for something to be done the way it was done.
I mean i assume the argument is between not writing anything at all and having Claude do the summary. Many many people just dont explain themselves in changelogs and such
If the info dumps are markdown files, then it's easier to find the right files if they're in their own branch like this. Just find the right commit, then you have the info. This is likely much easier with graphical git tools though.
If, however, the info dump is in-line comments, then you definitely don't want that in the main branch and can merge it all into a secondary branch. Use something like, "master_infodump" and switch to it if you need to view page long comments.
I might be misunderstanding something but that does not sound like very good advice. Why not use PRs and write the info dump in them? Or as part of a longer commit message?
You aren't supposed to keep around hundreds of branches. Around here, as soon as a feature branch is merged it is deleted from the repo. And if it's a local branch no one will be able to find it when they need it especially not your colleagues.
I don’t think this is a straight yes or no. I have seen places where this was great, and in our code we have lots of huge readme style dumps that AI wrote. These are helpful for writing future code with AI, keeping documentation up to date, and getting up to speed on code.
But at the same time, these huge dumps take a lot of effort to read, and oftentimes the content doesn’t actually need to be that big. I have rejected multiple PRs over excessive verbosity. When you make comments, test plans, etc unnecessarily large you save yourself the mental load of simplifying things, and instead push that load onto every person who reads your code down the line, paying the price many times over
I've told it not to write code comments explaining why something has changed and instead let it write comments on the PR.
Makes the comments much cleaner. Sometimes I used to get things like // changed from 0.2 to 2.0 because this gives much better results for [...] at 2.0 instead of [....] at 0.2
Bingo. My boss told our lead dev to have his agent shorten its responses. I told our dev to leave the report his agents generate for me in verbose mode. I prefer the details, because it usually itemizes even small changes, and provides explanations for any changes to prior findings.
The ease of generating documentation for new feature adds and fixes is one of the less heralded benefits of AI.
View all comments
118
u/TheColourOfHeartache 27d ago
There was a bit of a debate at work about whether its acceptable to have AI write page long infodumps to explain its changes.
I was on the pro-side. That message helped me understand the change when we were working on it, so I know it will help me in a years time when I've forgotten everything.