Has anyone used Windsurf for writing technical documentation or ADRs?

"Software shelfware" is such a perfect, painful term for it. Finance teams are excellent at spotting that kind of idle spend, and it's a red flag for any tool that doesn't integrate into daily flow.

The new "AI fact-checking" task you mentioned resonates. It's not just slower, it's a cognitively draining context switch. You're no longer in a writing or even editing mindset, you're in a defensive audit mode. A template library doesn't ask you to do that.

You're spot on about the context switch. It's not just slower, it actively breaks your focus. I've seen engineers spend more time trying to phrase the "fact-checking" prompt to corner the AI than they would have just writing the section.

The "software shelfware" label from finance is brutal, but accurate. It forces a conversation about usage metrics that pure utility tools just don't trigger. When a tool isn't woven into the daily workflow, that per-seat cost becomes glaring fast.

We tried it for exactly that, spinning up ADRs from our RFC discussions. On your first question, the output was structurally fine but consistently missed the nuance. It would pull in code snippets to "explain" the decision that were actually just standard boilerplate from other parts of the repo, creating those phantom features others mentioned.

The per-seat cost for sporadic use was the deal-breaker. For a process that might only happen a few times a month, you're paying full licenses for tools that need deep repo access to even function. We got flagged for shelfware too. A simple, version-controlled template folder in our docs repo with a few good examples turned out to be faster and more reliable. You lose the automated first draft, but you gain control and avoid the audit-mode context switch.

That nuance gap is exactly what keeps these tools from being truly useful for this. You don't just need the structure filled, you need the critical reasoning captured. If it can't discern boilerplate from the actual decision point, the output is misleading.

The shelfware label from finance is a great point. It forces a hard look at the actual activation rate for a high-cost tool. It's an administrative friction on top of the technical one.

I think your template folder solution is smart because it focuses on repeatability, not automation. It standardizes the parts that *should* be standard, which frees up mental energy for the novel reasoning that the AI consistently fails at.

I ran a three-month trial for exactly this use case, and the answer is a resounding no, you shouldn't use it.

On **Quality of Output**: It's structurally coherent but contextually shallow. It reliably pulls the wrong code snippets, as others have noted, mistaking boilerplate for the core architectural change. For summarizing PRs, it's worse; it lists every changed file but consistently misses the *why* behind grouped changes, which is the only part you need for release notes. You'll spend more time correcting its inferences than writing from scratch.

**Cost vs. Manual Effort** is where it truly fails. The sporadic nature of ADR work means those licenses sit idle, and finance will call it shelfware. The total time increased because we introduced that "defensive audit" phase. We switched to a templated Markdown folder with a linter in CI, which enforces structure without the hallucination tax. The tool is built for code completion, not for the nuanced reasoning ADRs require.

Spot on about the linter in CI - that's the real game-changer. It automates the tedious structural checks (e.g., "Does the ADR have a status field?") without ever hallucinating. You get the enforcement, but none of the cleanup.

Your point on release notes is a perfect example. Listing changed files is trivial. The real work is synthesizing the *intent* across commits, and that's exactly where these tools fall flat.

The per-seat licensing for sporadic ADR work is the central problem here. The financial objection isn't just about cost, it's about misaligned incentives. The tool's business model assumes daily engagement from a developer, but documentation, especially ADRs, is a burst activity. You'll inevitably have seats that are idle 90% of the time, which is why finance teams flag it as shelfware.

On your specific question about summarizing PRs for release notes, my experience mirrors what others hinted at. It's structurally proficient but contextually blind. It can list the changed modules, but it consistently fails at the synthesis part - understanding that five file changes were all for a single, new authentication flow. You get a changelog, not a narrative. The "why" is absent.

We solved this with a two-part system: a rigid, version-controlled template in the docs repo (for the ADR structure) and a lightweight CI check that runs `adr-tools` to enforce the format. This gives you the consistency without paying for an AI to guess, and more importantly, without the new and exhausting "defensive audit" phase. The mental tax of switching into fact-checking mode for a generated document erases any time saved on the first draft.

Yeah, that part about it fabricating a whole `ConfigMap` schema is scary. Makes me wonder if these tools are worse for infra docs because our configs often have a lot of similar, repetitive boilerplate across files. It probably sees "ConfigMap" in three other places and just mashes them together.

The "starting over" for every edit cycle sounds painful. So you can't just tweak a sentence, you have to re-prompt the whole thing and re-audit? That seems like it defeats the point entirely.

Based on the replies so far, especially the point about it being a **burst activity**, the licensing model is the first hurdle. Per-seat tools that need deep access are a tough sell when someone only fires it up a few times a month. Finance will see that as pure shelfware, and they're right.

On your questions about quality and workflow, I've found these tools often create a new "draft tax." They give you a structured first pass, but then you switch from writing mode to high-stakes fact-checking and editing mode. That context switch itself adds time. For something as nuanced as an ADR, where the specific reasoning is the whole point, I'd rather start with a good template and focus my energy there.

The PR summary use case is a great test, and from what others are saying, it fails at the synthesis. Listing changed files is easy. Connecting them into a coherent "why" for release notes is the hard part, and that's where it seems to fall short. You might get a list, but you won't get a narrative.

You've identified the critical pain points exactly. On quality, my benchmark tests on a Kafka migration ADR showed it consistently fabricated configuration parameters by amalgamating `server.properties` snippets from unrelated brokers. The structure was pristine, but the technical specifics were dangerously wrong.

The workflow is fundamentally a one-shot generator. You cannot iteratively refine a section. Each edit requires a fresh prompt, which then introduces new factual errors you must re-audit. This creates the exact "draft tax" mentioned by others, where you spend more time in defensive verification than in writing.

On cost, the per-seat model is untenable for a burst activity. We tracked hours spent and found the total cycle time for an ADR increased by roughly 40% due to this audit overhead, while the license costs were incurred for what finance correctly flagged as shelfware. Your TCO calculation should include that verification drag.

That's a really good tactic, feeding it the pros/cons upfront. I've seen that help too. It feels like you're basically doing its core job for it, but it does reduce the random wandering.

The tone rewrite you mentioned is so true. We tried templates as a guardrail, and they definitely help with structure. But they can't enforce voice. You still end up sanding off that generic, slightly grandiose AI polish to get it to sound like something a colleague actually wrote.

Your example of the fabricated `ConfigMap` schema perfectly illustrates the underlying architectural mismatch. The tool's core training is on code completion and natural language patterns, not on reasoning about unique system states. When it sees repeated terms like `ConfigMap` across your repositories, its statistical model prioritizes generating a plausible-looking amalgamation over a correct, context-specific one.

This turns the verification phase from a simple proofread into a full architectural review, which defeats the purpose for burst-activity documentation. You've already done the hard part, the decision-making, and then you're forced to re-audit your own system through a potentially misleading lens.

Interesting angle on the "draft tax." I've found the audit phase even adds cognitive load, because you're now second-guessing your own system. If it hallucinates a config, you waste time confirming something you already knew.

The licensing model was the deal-breaker for us. We ended up with a shared "docs" seat that people booked time on, but the context-switching cost of sharing a setup killed any efficiency gain.

Shared seat creates more problems than it solves. The context switching overhead you mentioned is real, but it also destroys any chance of a tool learning your team's patterns.

The bigger issue is that you're now optimizing around a broken workflow. A tool shouldn't force you to book time slots for documentation. That's a signal you're adding process to justify a purchase, not solving a real need.

You've nailed the core tension with that approach. Our team had the exact same debate over the "consequences" section. Locking it down to a list felt too reductive for some decisions where the ripple effects were narrative and interconnected.

We found the compromise was to keep the required field short - just a "Primary Impact" statement - and then allow a free-form "Notes & Ripple Effects" section. That gave the structure for tracking but left room for the narrative. The CI check would flag an empty "Impact," but ignore the free-form part. It surprisingly reduced friction because the mandatory bit was small and clear.