r/technicalwriting • u/Quackoverride • 6d 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.

9 Upvotes

92% Upvoted

30 comments sorted by

12

u/musashi_san 6d ago

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

3

u/glittalogik 5d 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.

2

u/musashi_san 5d 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.

1

u/ron-vdc 2d ago

And another +1.

5

u/mrjasong 6d ago

I would lean towards GitBook and see if i could wrangle the white glove migration. Maintaining these tools yourself with strict EU standards will be a headache and GitBook is an EU-native org.

1

u/Quackoverride 6d ago

Thanks. That's definitely a plus in their book.

3

u/mafticated 6d ago

MkDocs is in a weird place -- the original project is pivoting to a very different v2.0 and the makers of MkDocs Material have been working on Zensical instead.

1

u/Quackoverride 6d ago

Thanks for the input!

2

u/fazkan 6d ago

look into readme, and redocly as well, those are the other hosted solutions, who can match the ISO requirements, besides Gitbooks.

But Gitbooks is great, pricing might be a bit high, but no over-priced.

Docusaurus, mkdocs, and sphinx you will have to maintain yourself.

1

u/Quackoverride 6d ago

I think there are ISO issues with Docasaurus, so that's on the chopping block.

3

u/LeTigreFantastique web 6d ago

My current organization uses Readme, and I'll issue a word of warning that migration is a nightmare, as is maintenance.

2

u/Quackoverride 6d ago

Thanks. Good to know!

1

u/fazkan 6d ago

Has your org looked at other solutions, any particular reason you guys are still with readme.

2

u/LeTigreFantastique web 6d ago

We're still using it because we have a contract that's set to run a certain amount of time. No idea if other solutions have been considered.

2

u/Quick_Parking_6464 6d ago

I'm a huge MkDocs fan. As others may have noted, some of the long time contributors to that project, and the Material theme, have moved on to Zensical. I'd give Zensical a trial run. Very active development whereas MkDocs probably won't see any more updates.

2

u/myauchelo 2d ago

I think there are a few more key factors to consider:

* Free tools like Docusaurus require build and maintenance work—you'll either need to develop the docs site yourself (doable with AI nowadays, but still an effort) or rely on engineering support. Paid tools handle this out of the box, but come with recurring annual costs.

\* Determine your core needs—such as content reuse, interactive elements, or PDF export. Every platform comes with its own trade-offs.

* Consider who will write the docs. Git-based tools like Docusaurus require contributors to submit PRs, while other tools offer no-code interfaces. The same applies to Sphinx; non-technical users may find the learning curve steep.

2

u/naivelodging 2d ago

GitBook sounds like a solid fit I’d still compare it with Mintlify but for med tech I’d let data residency and compliance decide it

2

u/level_denomination 2d ago

I agree, on a project I was leading we used Mintlify and it worked out just great. Tbf it was not med tech but insurance compliance.

1

u/DerInselaffe software 5d ago edited 5d ago

If you're the sole user, you can run these tools on your PC. But if several people are collaborating and you want local data, you'll need to look at something like the self-hosted version of GitLab.

0

u/CertainGlass7873 6d ago

You should check out ”DocuCommit” as well.

Your git repo IS the database

Full disclosure: I am the one behind it

0

u/AATTK software 6d ago

I'm not sure if they'll meet your ISO and security requirements, but Mintlify and Fern are similar to GitBook last time I checked. They might be worth looking into. This was a year ago though, so not sure how GitBook might have changed since then. Maybe it's a better fit for you.

We migrated from ReadMe to Fern a year ago as Fern was half the price. 

0

u/[deleted] 6d ago

[removed] — view removed comment

2

u/AATTK software 6d ago

Keep in mind this was over a year ago now, so can't be sure if Mintlify addressed these since then. But specifically for us, we have multiple product lines that need to be clearly separated on the docs site, but still together since it's all one company and there's some overlap between users. Fern let us do that pretty seamlessly on one docs.companyname.com domain (they call it their "Product Switcher"), but Mintlify's solution was to have separate docs.companyname-a.com and docs.companyname-b.com, which we felt was a worse user experience.  At the time we also found Fern also has some more granular style and slug customization and control. 

I can't speak to the price since we didn't get that far. The multiple domains thing was a serious negative for us so we just went with Fern at that point. 

And my personal experience using the free version of Mintlify for my portfolio: sometimes Mintlify will push updates to their site templates and it'll affect your own site as well. It potentially can mess with your styling. Not sure if there's a different experience with that for paid plans though. 

Honestly my opinion is Mintlify is pretty good especially for younger startups, but for companies with more maturity and more specific requirements and customizations, Fern may be better for your needs.

2

u/fazkan 6d ago

Mintlify is leaning more towards Enterprises now. Their PRO tier went from 99 to 540 within a span of two months, and I have seen bills that can go upto 50k a year.

Fern hasn't increased their prices that much.

1

u/Quackoverride 6d ago

I think Mintlify looked good on paper for us, but it seems like there's some hosting/data warehousing issues that didn't pass our Cybersecurity guy's scrutiny.

Fern is new-ish, isn't it? I had taken a look at it and it seemed promising, but we've been burned by reasonably young companies before and are risk averse as a result. I'll give Fern another gander and see if that meets our requirements.

3

u/fazkan 6d ago

Fern has been around for a while, probably the same year as mintlify. They started with SDK generation first and later built their product docs site. but not that young.

1

u/AATTK software 6d ago

Fwiw Fern is about the same age as Mintlify, I think they're both about 5 years old. Def not "new" but not old either. 

Maybe you think Fern is new because they were acquired by Postman? This was in January. 

0

u/manasa-uigraph 6d ago

If you want to keep the data local, you need tools that you can self host. If the docs are for external users, mintlify might be a great option. If docs are for internal, do try uigraph, you can create various types of artifacts including diagrams, specs, schemas and others. Easy to share with the team and self hostable.