Swapnil Ogale - Putting the “tech” in technical writer

TL;DR

Writers can build technical credibility by learning how documentation tools store and render content (e.g., XML inside docx files, XML views in help authoring tools, and XML-based SVG images).

Briefing Cornell Notes

Briefing

Technical writers don’t need to become full-time developers to bring “tech” into their work—enough command of the tools, workflows, and text formats behind docs-as-code can level the playing field, speed collaboration, and make publishing and review less painful. Swapnil Ogale’s core message is that the path to docs-as-code starts with looking under the hood of the authoring tools already in use, then gradually adopting the same plain-text, version-controlled, automation-friendly workflow used by software teams.

Ogale begins with a personal setback: after a long interview and a technical writing test for a developer documentation role, feedback singled out a lack of “tech” despite a portfolio built with Markdown, Hugo, and static-site tooling. That experience became a forcing function—technical writers often communicate well but fail to demonstrate technical capability in ways hiring teams recognize. The fix isn’t to abandon writing; it’s to show technical fluency through how documentation is produced, reviewed, and delivered.

Before jumping into docs-as-code, Ogale argues there’s already plenty of “low-code tech” inside traditional documentation tools. Microsoft Word’s docx files contain XML that can be edited directly (even with a basic text editor) to recover or modify content. Help authoring tools such as Madcap Flare offer split views that reveal underlying text and XML, helping writers understand how styles render. Even images can be treated as editable artifacts: scalable vector graphics (SVG) are XML-based, so callouts and layer changes can be made in a text editor. The takeaway is practical: writers can learn to manipulate documentation programmatically without waiting for a perfect docs-as-code setup.

From there, Ogale lays out what changes when moving into docs-as-code. The lifecycle still includes planning, gathering subject matter expert input, and review—but the review experience improves because documentation flows through the same tools and workflows as the product team. Toolchains typically include issue tracking, plain-text authoring (Markdown, reStructuredText, AsciiDoc), version control (often Git), and automation for previews and publishing. Processes can mirror agile/Scrum cadence so the team knows when documentation work is happening and when it will be reviewed and released.

A major learning hurdle is Git. Ogale recommends learning “just enough” to contribute meaningfully, starting with core commands and using graphical Git tools if the command line feels intimidating. He also describes a GitHub Flow-style workflow: documentation changes live on feature branches, go through pull requests for review, and merge back into a protected main branch.

Plain text is positioned as the writer-friendly engine of docs-as-code. It separates content from presentation, makes diffs readable, and reduces collaboration friction because fewer people need specialized review tools. Previews become faster too: instead of manual PDF cycles and separate document management steps, continuous integration and continuous delivery can rebuild and publish documentation automatically when commits land in the repository.

In Q&A, Ogale adds that Git learning can come from coworkers plus resources like the Git book, and that Markdown can support translation/internationalization (though he personally hasn’t worked deeply in localization). He also notes that reusable components in Markdown can be trickier than in dedicated help-authoring systems, especially when tables or complex structures don’t render cleanly inside snippets.

Overall, Ogale frames docs-as-code as a repeatable skill-building journey: stay curious, keep learning technology around the product, and treat “putting the tech in technical writing” as an ongoing practice rather than a one-time transition.

Cornell Notes

Swapnil Ogale argues that technical writers can add real “tech” to their work without becoming developers by adopting docs-as-code practices. The first step is learning what’s already inside common tools—Word’s docx XML, Madcap Flare’s XML views, and SVG’s XML structure—so writers can manipulate documentation programmatically. Moving into docs-as-code then means using plain text (Markdown/reStructuredText/AsciiDoc), version control (especially Git), and automation for previews and publishing via CI/CD. This alignment with software-team workflows improves review speed, transparency, and collaboration while making publishing less manual. The result is documentation that fits naturally into pull-request and continuous delivery pipelines, reducing friction for both writers and subject matter experts.

Why does Ogale treat “tech” as something writers often fail to demonstrate in hiring and collaboration?

He describes a developer documentation interview where, after extensive conversations and a test, feedback emphasized a lack of “tech,” despite his portfolio built with Markdown, Hugo, and static-site tooling. In hindsight, he concludes that writers may communicate well but don’t always show technical capability in the ways teams recognize—especially when documentation work is expected to integrate with developer workflows like version control, pull requests, and automated previews.

What “low-tech” entry points does Ogale recommend before adopting docs-as-code?

Ogale points to hidden structure inside familiar tools. Microsoft Word’s docx files contain XML that can be edited with a simple text editor to recover or modify content. Madcap Flare provides split views that show plain text and XML so writers can understand styles and rendering. For images, SVG files are XML-based, letting writers edit layers or add callouts directly in a text editor.

How does docs-as-code change the documentation lifecycle compared with traditional authoring?

The core steps—planning, gathering subject matter expert input, and review—remain. What changes is the review and publishing experience: documentation moves into the same toolchain and workflows as the product team, so review can happen through pull requests and previews can be automated. That reduces overhead from manual PDF cycles and separate publishing steps.

What does Ogale say is the minimum useful way to learn Git for docs-as-code?

He recommends learning “just enough” to contribute meaningfully: start with a small set of core commands, then use graphical Git tools if the command line is intimidating. He frames Git as a key building block for docs-as-code and ties it to a common workflow (GitHub Flow), where changes happen on feature branches and merge back into a protected main branch after review.

Why does Ogale call plain text a “writer’s dream” in a docs-as-code workflow?

Plain text (Markdown and similar formats) is easy to read and write, lightweight, and platform-agnostic. It also pairs well with version control because diffs clearly show what changed. Collaboration improves because fewer people need specialized tooling to review content, and rendering can be handled by the documentation build system rather than by the authoring editor.

How do CI/CD and previews reduce friction in docs-as-code?

Instead of manually updating PDFs and waiting through document management and approvals, CI/CD can rebuild and publish documentation automatically when commits are pushed. Previews can be generated per topic or for the whole site, giving faster feedback loops and making publishing largely a “robot” task once automation is set up.

Review Questions

What specific examples does Ogale give to show that traditional documentation tools already expose XML or programmatic structure?
In your own workflow, which part would be hardest to change first: Git branching/pull requests, plain-text authoring, or CI/CD previews—and why?
How does plain text improve collaboration and version control diffs compared with WYSIWYG authoring tools?

Key Points

1
Writers can build technical credibility by learning how documentation tools store and render content (e.g., XML inside docx files, XML views in help authoring tools, and XML-based SVG images).
2
Docs-as-code improves review by routing documentation through the same pull-request and workflow patterns used by software teams.
3
A typical docs-as-code toolchain combines issue tracking, plain-text authoring (Markdown/reStructuredText/AsciiDoc), Git-based version control, and CI/CD for previews and publishing.
4
Git learning should be incremental: focus on a small set of commands and consider graphical Git tools to reduce intimidation.
5
Plain text reduces collaboration friction because it’s easy to review, diff, and render consistently, with formatting handled by the build system.
6
Automation (CI/CD) replaces slow manual cycles—commits can trigger builds and publishing, letting writers focus more on content than delivery mechanics.

Highlights

Microsoft Word’s docx format contains XML that can be edited with a basic text editor to recover or modify documents—an immediate “tech” entry point for writers.

Madcap Flare’s split view exposes both text and XML, helping writers understand how styles render in the final output.

Docs-as-code aligns documentation review with pull requests, turning subject matter expert feedback into a faster, more transparent workflow.

Plain text pairs naturally with Git diffs, making it easier to see exactly what changed between documentation updates.

CI/CD can automate previews and publishing so documentation delivery no longer depends on manual PDF cycles and separate approval steps.

Topics

Docs-as-Code
Plain Text Authoring
Git Workflow
CI/CD Previews
Technical Writing Tools

Mentioned

Swapnil Ogale
API
CI
CD
XML
CSS
SVG
Git
CI/CD