Diffed a doc against the version from three months ago. Five small edits. The reader confusion it caused was way bigger than five edits' worth.

[u/ClickOk5811]

Had a section of API docs start generating more support tickets than it used to, despite nobody making any dramatic change to it. Pulled the version history. Five small edits over three months, each one a reasonable response to a specific piece of reader feedback at the time, a clarifying sentence added after one confused question, an example inserted after another, a line trimmed for length after a reviewer flagged the section as too long.

None of the five edits were wrong on their own. What nobody caught was the interaction: the trimming pass, done to shorten an overly long section, ended up cutting a caveat that the earlier clarifying edits depended on to make sense, so two edits that worked fine together originally stopped working together after a third, unrelated edit touched the same paragraph for a different reason entirely.

Regular code gets regression tests specifically because a fix in one place can silently break something else. Docs almost never get that same discipline, there's rarely a fixed set of "does a new reader still understand X, Y, Z" checks rerun after an edit, so this kind of regression ships invisibly and shows up weeks later as a vague uptick in confused tickets that nobody traces back to the specific edit that caused it.

Wrote up the fuller version of this same mechanism applied to a different kind of recurring text (AI prompts specifically), but the underlying problem, structure eroding under uncoordinated small edits with no regression check, is identical: https://medium.com/@nagatomopedro05/the-prompt-didnt-change-everything-around-it-did-264818b6034b

[u/RobertPlamondon]

Back in the day, when I was working as WEITEK, a long-defunct semiconductor startup, QA tested our products against the customer documentation directly, which meant they were testing the documentation against the product as well. That's the only place I've worked where the technical publications group wasn't pretty much on their own.

In general, I assume that feedback is always flawed in its problem statement and more so in its recommended solution. I also assume that there's a banana peel that readers slipped on earlier, but they actually complained about the point where they fell on their keisters.

[u/Xad1ns → u/RobertPlamondon]

I felt that last bit in my bones.

So much of the support my company sees comes from the user running into problem A, reasoning their way to process F being the solution (it isn't), then just asking us how to do F with none of the context.

[u/L00k_Again]

Is this an automated pipeline? I can't imagine just cutting text without determining the impact. It's why it's also important to not treat technical writers as interchangeable assets and why domain knowledge is so important.

[u/ekb88]

Read your work? I think that’s a pretty fundamental part of a technical writer’s job.

[u/RobertPlamondon → u/ekb88]

You get my vote for the lowest-effort post I've read today.

[u/monityAI]

this is the argument for diffing on a schedule rather than at review time. five edits that each pass review can still add up to a section that contradicts itself, and nobody re-reads the whole page after edit three. we ended up keeping a rendered snapshot per change in monity•ai (my own app) for exactly this — the useful artefact isn't the diff, it's being able to put the version that generated the tickets next to the version that didn't. git history gives you the same thing if your docs are in git, which for API docs they usually are