Those of you who work in an organisation that makes heavy use of GenAI coding assistants: how did you educate your developers that if they automate sweeping changes to user-facing code, they MUST also automate the corresponding sweeping changes to user-facing documentation?
Or have you identified a strong correlation between embracing GenAI coding assistants and not giving a flying fuck about user-facing docs?
@xahteiwi TBH is on of the parts in which AI has improved things the most:
a /document skill.md not only instructs Claude to do a diff and update docs accordingly
@xahteiwi Happy to help you parse it!
Your original question was about how teams handle the relationship between large, automated changes to user-facing code produced with/by GenAI and the corresponding need to keep user-facing docs in sync.
My answer was that, in my experience, this is actually one of the areas where AI helps the most.
Specifically, we instructed Claude explicitly to:
1) analyze the diff of the changes made to the code… (1/2)
2) identify which parts of the documentation are impacted
3) update those parts accordingly
In our case, a simple instruction such as “/document skill.md” can guide the model to:
- read the modified code
- compare it with the existing documentation
- apply consistent updates where needed
So rather than increasing the gap between code and docs, these tools can reduce it, provided they are used intentionally. We really never had better docs, and more up-to-date, than now. (2/2)
Florian Haas
Cesare Forelli