Comment by ericyd | Hacker News Reader

Comment by ericyd | Hacker News Reader

I disagree, requiring code review for docs changes sounds great but in my experience it's extremely hard to get a human to review docs changes. Either you get a rubber stamp with no real review (zero added value, adds useless friction) or you spend days bugging people to actually review your changes. All for docs!

The counter-argument i envision is: "update your docs and code at the same time in the same PR!" That works great, until you want to document something that isn't precisely tied to a single piece of code. In fact I think the most useful docs describe high level systems rather than being associated with specific pieces of code. Use comments for that; in contrast, docs should be easily editable by anyone at all times, otherwise they never get updated (an evergreen problem in any scenario).

This is one of the arguments for polyrepo: different sources have different sensitivities. Code ending up in production needs to be reviewed, so enforce reviews.

Docs do not.

So what results is either allowing developers to push (but not force push) directly to main (you can always push revert commits if needed), or a PR process that exists to enforce linters and build-ability, but if those pass, allow the developer to merge independently, without human review.

Agreed, but I think the review & CI system should ideally be able to ignore markdown changes. Easier said than done.

But I think the biggest benefit, which we shouldn’t overstate, is that agents will just update docs as they find them. Including for big picture systems. Keeping docs updated is a PITA.

Writing style of AI often sucks. But I’ve found it pretty easy to rectify. And having some correct context is better than nothing or outdated docs in a lot of cases.

This'll be a controversial answer, but this sounds like exactly the sort of thing an LLM should be able to do reasonably well, whether by the human writing the docs and the LLM updating the code accordingly or by the human writing the code and the LLM updating the docs accordingly.

Reply on news.ycombinator.com