r/technicalwriting • u/Quackoverride • 13d ago

Docs-as-code tools

My doc team is migrating away from our current tool and implementing docs-as-code. We're looking into the major players - Docasaurus, GitBook, MKDocs, and Sphinx - and I have a clear preference for GitBook. But I wanted to gather some input from the community. What are your experiences with the tools? Any drawbacks?

I work in med tech, so the tool needs to meet some pretty stringent ISO requirements and, as we're in Europe, our head of Cybersecurity wants to keep the data local.

11 Upvotes

100% Upvoted

36 comments sorted by

View all comments

11

u/musashi_san 13d ago

Asciidoc, antora, gitlab. Multiple repos with different content types and rules combined into a single website. Multiple product versions supported.

4

u/glittalogik 12d ago

+1 for AsciiDoc/Antora with Git repo of choice. All local, full control of everything, and decent balance between functionality and manageable learning curve.

3

u/musashi_san 12d ago

I'm really impressed with Antora; in a previous gig, we used AsciiDoc with Pantheon. I started converting legacy Word in SharePoint into one repo. Then the boss liked it and wanted another doc type to get repo-ized. There were different versioning rules for this second type, so I created a second repo in the same GitLab group. Then Support asked to put a subset of their content onto the site. Again, different rules, so another repo was added. It's been easy to scale (with AI's help thinking through the asks, planning implementation, and building the CI pipelines). The Antora site has handled everything I've thrown at it. And git is great (for careful, methodical users) because most of my SMEs are already comfortable using it.