Part of my role as the Head of Developer Experience includes being the Directly Responsible Individual (DRI) of documentation. This is exciting in that I get to craft the documentation experience, but less exciting that I get to inherit and work through years of not having a DRI of documentation. Yay growth!
I mention this because I wasn't in my role (or at this company) when the engineers decided to move forward with Docusaurus, a React-based documentation framework. I think the choice they made was reasonable, probably the choice I would have made if I was in their shoes, but not the choice I would have likely made today.
If this is the first time you are hearing about Docusaurus, I recommend reading their introduction before continuing.
I've had a few folks reach out and ask my opinion on Docusaurus, why I say I wouldn't have chosen it, and how I'm making it work for us.
So here's my pros, could be pros or cons, and cons list.
Pros
The positive aspects.
Markdown and frontmatter
This just works for us as a team and organization. Markdown is comfortable for most people and frontmatter helps use add critical metadata like keywords, descriptions, etc. that may not work their way into the page otherwise. The feels like Jekyll or even this editor on Dev(!!!) and I like that. It's a great fit for my team and our engineers (who author our content).
Flexible to extend with React
Written in React, so you can customize it with React. Not a lot to say here other than this makes me feel like I'm not boxed into a corner.
Search
Algolia DocSearch is super powerful and I was thrilled to see it as a touted option here for search. I do have more to say on this topic, but it's unfortunately a con.
Could be pros or cons
After reading what I outlined for this section I realize these are mostly not neutral and more con-leaning. What do you think?
MD files can contain both content and code
See tabs for an example.
Now there is nothing wrong with this except I like separation of content and functionality, so to me this is more of a con. Maybe this makes me old, but I'd rather have my content in one place and the code running the presentation of the content in another place. Part of this thinking is because for us this could be two people maintaining each distinct piece.
By default, whatever are the first chars in your files are the description preview
This one snuck up on me. If you use tabs at the top of your page, like the example in the above section, the first chars on your page are code. So you get something fun in your short description preview like {object} or {children}. If you are lucky your page might start with another header, so you just get one word like "License".
Luckily you can fix this by adding a brief sentence or using frontmatter's description but finding these seems to require testing in production. My technical writer and I either use Google Search or sending links in Slack to see what the short descriptions were. Is there a better way? I haven't found one.
Cons
These are irritating.
No built in feedback mechanism
This is huge for my team. We have no way to measure engagement with our individual documentation pages either through comments, stars, or a thumbs up/down.
While we are an open source-minded company and our docs openly accept PRs and issues, we see people more comfortable with posting to the forums or Slack about a docs issue or clarification. Even the link to "Edit this page..." doesn't include our contribution guide, leaving users confused about the process or what to include in the PR initially.
Having closely-coupled (or more closely-coupled) feedback mechanisms would be tremendous! We could write a custom plugin for this and it's on our roadmap, but this frequently comes up in discussions about Docusaurus.
Algolia DocSearch
I think Algolia DocSearch is super powerful, but when we were having issues with it, I couldn't figure out where I needed to make a change. Did I need to make the change in my docs source? In the Algolia UI?
Turns out, there was a 3rd option unknown to me!
Algolia DocSearch maintains a separate config repo for all their customers. If you want to update your config, you'll need to find it in their repo and submit a PR (with some info that you are, in fact, involved with the documentation project you are updating).
The only way I figured this out was after stumbling across their docs and finding this playground. Entering in our site and search data, the experience WAS TOTALLY DIFFERENT AND EXACTLY WHAT I WANTED.
In the process of me updating our config, I found out the config was super outdated and contributing to our overall horrendous search experience we had been desperately trying to fix for months.
That config change was merged quick and almost instantly all the search issues we were experiencing just corrected themselves.
This experience feels disjointed, but we'll have it documented so we (hopefully) don't have to go through this again. Still unsure when we would know we need to update the config on the Algolia repo.
What generates the sitemap?
Is it Algolia DocSearch? Do you need the plugin?
This is related to the above ramblings. It looked like we didn't have a sitemap without adding config to create one. Then when looking at the Algolia repo it includes a parameter for a sitemap, I assume for search? Are they different? Do they refresh the same?
Trailing slashes...
You have the ability to enabled or disable trailing slashes, but somehow we ran into massive issues with trailing slashes added to URLs. The initial page loaded just fine, but every subsequent page may not load, may 404, or may just look like it's loading forever and not really do anything.
We disabled trailing slashes and I still see some weirdness when loading links. Is that from a redirect config issue? Is that something with my cache? Is it still this trailing slash thing back to haunt me? I have no idea.
Limited plugins & integrations are... weird?
Google Analytics and GTAG are available in plugins, but of course, our marketing team uses something different - GTM, Google Tag Manager. Neither of these plugins worked how we wanted them to with GTM.
After building a custom plugin, Universal Analytics didn't seem to load when GA4 did just fine. This led to interesting conversations around adding custom event fires for each page (??? hard pass). This then led to all sorts of issues and data confidence concerns. We tweaked the custom plugin, threw it out for one we found online, and then gave up trying to make Universal Analytics work knowing GA4 is the future anyway.
Right before all of this we were also implementing a cookie consent tool called Osano and it straight up borked the entire site. Not sure I can blame Docusaurus for that bit, but it was frustrating.
Documentation tools and products I've worked with in the past were more mature and offered robust integrations with more enterprise-y tools. Not saying Docusaurus can't get there, it's just not there yet.
No built in snippets
I really like this feature on most documentation products made for technical writers. Snippets allow you to write once and apply it to many different pages or articles. This is great for writing your blurb about how to download or install something, access premium or Enterprise features, and other things that tend to appear on many pages across your documentation corpus. Could we build a custom plugin or component to make this happen? Sure. But it's unfortunately not high on the priority list.
Pulling my thoughts together
I don't hate Docusaurus.
My perspective and list will be different than yours. If I was a full-time front end engineer, like in my past life, this would be a great documentation framework for me to use. But unfortunately, I know too much now 😅.
My docs team doesn't have an engineering resource, so while Docusaurus is flexible, I need time from someone with a React skill set or I have to do it myself. Sometimes I get time from the engineers, sometimes it's not a priority higher than their product priorities. Rarely do I have time to do this myself.
I also need to tap into tools I didn't have a hand in choosing- Osano and Google Analytics. While we figured out a way to make this compatible, it took far longer than an OOTB plugin.
All of this to say, we can make it work.
Looking ahead, because the content is all Markdown, if we do have to pickup and leave to another framework or documentation product, it will likely be relatively easy to move on. While that didn't make the pro list exactly, it's nice to see we've set ourselves up for the future that doesn't punish us for where we are at today.
Do you or your team use Docusaurus? What are your thoughts?
Top comments (4)
so what is your alternative, is it dev.to/missamarakay/achieving-a-do...?
Could gitlab.grnet.gr/terminology/docusa... solve the lack of snippets?
Missing that in core driving me nuts as well.
I would like to have simple glossary at the end of documentation.
@packelend I somehow missed your comment! I'm so incredibly sorry.
What is my alternative to Docusaurus? Well, we are currently still using Docusaurus and I've hired an engineering for docs infrastructure to address some of the concerns I listed above. I should revisit how we are using Docusaurus in a new blog, but I'm not exploring alternatives at this time.
I REALLY like your link suggestion. I noticed the project was deprecated but available here - github.com/grnet/docusaurus-termin...
In fact, I like it so much, I want to add it to my team's backlog!
but late than never
so I hope the best, that it becomes maintained again :)
As the Docusaurus maintainer, I addressed some of the cons here: twitter.com/sebastienlorber/status...