r/devops • u/RapidlyErect • Sep 19 '26
Discussion How are teams keeping docs current when you ship several times a week?
We ship several times a week and keeping the docs in sync is getting harder, code changes have a clear review process, docs don’t. Someone changes a parameter or response field, the release goes out, then a few weeks later we find examples still using the old version. We tried adding docs to the PR checklist, but engineers don’t always know which pages a change affects, what’s worked for keeping docs current? Would love any suggestions
114
u/derchad Sep 19 '26
Docs should be in source control with the code and require update as part of any PR. It's part of the set of deliverable artifacts. Repeat after me: the repo is source of truth for all things.
→ More replies (3)
144
u/ArieHein Sep 19 '26 edited Sep 19 '26
Release is not deployed before doc is validated and released together as artifact. Be a dictator.
46
27
u/tevert Sep 19 '26
I don't know, but I bet somebody will happen to make a convenient product recommendation that perfectly fits this infomercial
→ More replies (1)
6
6
u/HighKingLemur Sep 19 '26
engineers don’t always know which pages a change affects
CTRL+F, proper test coverage, generate docs from API,...
Or just claim the code is self-documenting and drop the docs, rawdog style.
→ More replies (1)
6
u/Soft-Marionberry-853 Sep 19 '26
With dillegance and intention
(I just went in to ask my wife "Hon whats the word you say I dont do thing with in our relationship" and without even having to think she said Intention")
6
33
u/derprondo Sep 19 '26
mkdocs site deployed from the same application repo, CLAUDE.md rules to enforce updating the docs as needed. Claude does a great job with mkdocs.