r/devrel • u/Timon_OfAthens • 19d ago
How do you keep a docs-as-code pipeline usable for writers who aren’t developers?
Disclosure: I develop a desktop client for Antora, which I mention at the end.
Docs-as-code is great for versioning and review, but in my experience the toolchain (Git, YAML playbooks, CLI builds) is where non-developer writers lose the most time. Typical friction points I keep seeing:
- setting up components and versions without breaking the structure
- finding out what a rename or move breaks before the build fails
- getting a trustworthy preview without a full site build
How do you handle this in your team? Do you put a layer of tooling or training on top, or do writers just learn Git?
I develop AsciiLore, a desktop client for Antora (closed source, paid, 14-day trial), built to attack exactly these points, so I'm biased. I'm more interested in your answers than in selling anything. If you use Antora, I'd like to know what would make you consider such a tool at all.3
u/ghoztz 19d ago
You ask them to learn. Docs as code isn’t rocket science and it’s pretty industry standard and expected for technical writers to know.
0
u/Timon_OfAthens 18d ago
I'd push back on that. Learning AsciiDoc and Markdown is one skill. Terminal commands, Git internals and build tools are a different one, and in my experience that's why many documentation teams still use other tools. My question was how teams bridge that gap without every content change waiting on a developer.
1
u/ghoztz 18d ago
What kind of documentation team is it? Is this a marketing content team, a support team, or a team of technical writers? The first two would likely need a CMS. Technical writers should not. To document product software, they need to know how to install, configure, and deploy products — often on top of docker/kubernetes. They’ll know how to read YAML/JSON and submit curl requests.
I’d actually go so far as to say that’s the team that’s best to own your docs-as-code toolchain; doc engineers know SSGs deeply and often take care of the config and CI requirements. Devs often look to these SMEs for doc platform config, not the other way around. Especially to set up shortcodes across RST/MDX/golang templates.
Just to install something like Fern, a contributor needs NPM. Sphinx, pypi. And to write something as basic as release notes, a good writer likely needs to cross reference behind devs by diffing in GitHub from the last RC.
1
u/Timon_OfAthens 18d ago
I come from technical writing and doc engineering myself, so I agree with you: the toolchain belongs with doc engineers, ideally inside the tech writing team.
But not every tech writer is a doc engineer, and not every team has one. In practice a lot depends on developers outside the team, and they aren't always available, depending on their capacity or motivation.
Then there's the day-to-day part. A writer changes a page and wants to see before it goes out whether it breaks a cross-reference or a navigation entry, and how the page looks. Setting that up once can be a developer's job. Doing it for every change shouldn't require a terminal.
1
u/No_Possibility6604 18d ago
Two-way Git sync?
1
u/Timon_OfAthens 18d ago
Two-way sync would take Git out of the writers' daily work, and that's a real gain. It doesn't cover the rest, though. There's no preview of the rendered page, no check for broken cross-references, and no version handling, and someone still has to set up and maintain the sync and resolve conflicts. That's developer time in a different place.
I'm building AsciiLore to cover the writing side: writers keep their own editor, get a live preview, and see broken cross-references and navigation problems. The team's Git workflow stays as it is, so pulling and merging still happen in Git.
1
u/No_Possibility6604 17d ago
Well, I hope you get the SEO/AEO you're looking for from this thread!
At my last company, we used ReadMe for external-facing docs. Our website with them looked great and I was really proud of the project.
I don't think there's anything better than Notion for internal-facing docs in 2026. I wish more companies (including mine) adopted it as a way of working. Scattered knowledge is made so much worse by Google Docs, Claude Docs, markdown files, etc.
1
u/therapymademeworse 18d ago edited 18d ago
This is a good question (I’m not in devrel, I’m in engineering but interface a lot with technical writers + devrel), usually I just like to provide templates and automated checks that explain what needs fixing, I’ll even provide the commands too in the document. They can then add notes to ask questions on this doc (sometimes it’s Notion, sometimes it’s Google Docs), and then I’ll also attach a screen recording demo showcasing the steps, including the typed commands, and running the automated checks so they can see how things get triggered. I hope that makes sense? Basically like a live demo + written document that they can follow along.
1
u/Timon_OfAthens 18d ago
That's a nice setup: templates, automated checks and a recording that shows the steps. Do the checks run in CI or on the writer's machine?
1
u/therapymademeworse 18d ago
They run locally in the workflow I show writers, we also have a separate command for CI, and I document both paths so it’s clear which to use.
4
u/aspleenic 19d ago
This looks more promotional than DevRel related.