When the right recommendation still failed.

NCR’s product portfolio spanned point of sale, self-checkout, ATM, and backend processing across many industries, and all of it needed documentation for internal and external support and professional services. Years of acquisitions had created a mess — teams writing documentation in multiple formats on multiple tools. New IT leadership set out to consolidate everything into a GitHub-and-Markdown system, and as owner of NCR.com and the MyNCR customer portal, I was put on the transition council.

IT wanted to centralize and simplify. Migration to GitHub for software projects was already underway, and physical-product technical documentation was next — which meant everyone would adopt Markdown. The technical writers began voicing concerns, unspecified at first. IT proposed discovery and a proof of concept, but behind closed doors the conclusion was already settled: a GitHub-and-Markdown workflow would be the answer.

The writers’ gripes came across as two vague lines — “Markdown’s going to make everything take longer” and “I need to publish for different people.” To IT, that sounded like challenges to solve at best, and a spoiled group resisting change at worst. I suspected there was more to it, so I spent time working alongside the writers and briefly embedding with them to see how tools like Adobe FrameMaker and MadCap Flare actually addressed their work.

The first concern unpacked into real things: content reuse through snippets, variables, and components for single-source-of-truth writing; clean export across XML, HTML, and PDF that purpose-built tools were designed for and Markdown would require custom code to match; and link management and topic governance built into the writing tools that Markdown would push back onto the writer. The second concern was just as concrete — documentation isn’t monolithic. Conditional publishing for internal versus external, admin versus basic, was mandatory, and translation multiplied it. Where translation was legally required, like French Canadian, it created real risk for the writers responsible.

There was a cultural layer underneath. The writers were wary of changes imposed by non-experts that might end in staff reduction — recent layoffs had unsettled all of them. Their concerns were valid, but they’d dug into their position and were doing a poor job explaining the reality of where Markdown complicated the workflow.

I didn’t lead the effort, but I’d built a trusted position with both the technical writers and IT leadership. My recommendation was to prioritize the writers’ shift into GitHub while allowing continued use of MadCap Flare and Adobe FrameMaker, and to charter a technical-writer guild around a centralized toolset and ongoing research into fuller Markdown adoption.

The recommendation was sound, and it created a framework change could proceed through. But it failed to address the reality that IT was making an executive change and was willing to force the writers to adopt it regardless. In the end no change happened at all — months later the world met the COVID-19 pandemic, and the effort dissolved into it.

Once I understood both the legitimacy of the writers’ publishing concerns and the immovability of IT’s position, I should have asked for an engineer and built a docs-as-code publishing system as the proof. An automation server like Jenkins could have addressed the first concerns directly — format publishing and link management — turning the debate from opinion into a working demonstration. That might have produced a more productive consensus: IT giving credence to the writers’ concerns, and the writers gaining an engineering resource to meet their legitimate needs. The recommendation was right on paper; what it lacked was a proof that made the right answer undeniable.