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).
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.
ericyd · · focus · HN ↗
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).
anon7000 · · focus · HN ↗
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.