Tim Post
echoreply

echoreply

Here's Why I Can't Stop Talking About Docusaurus.

We've come a long way with many things; I'm glad the tools that we use to teach are catching up.

Here's Why I Can't Stop Talking About Docusaurus.
Tim Post's photo
Tim Post

Published on Oct 10, 2021

8 min read

Photo by Daniel Cheung on Unsplash

I love wikis. I mean I really love wikis. Really really love wikis.

I came to know Wikipedia in the early 2000's after hearing a friend talk about a movement that was going to end the paper and CD ROM encyclopedias once and for all. After having spent the previous five years running a successful dial-up BBS, the Wiki concept of completely open trust through transparency really changed the way that I thought about re-engaging a user base that was quickly shifting to AOL. As long as it's easy to spot and roll back vandalism by bad actors, what happens if we just let anyone that wants to write paragraphs about something just do it, and focus on giving them great tools to work with? That was a pretty wild concept where security through obscurity was still seen as tenable.

It wasn't just the model that was novel, it first changed the way I think about optimization in systems designed for humans. It taught me that optimizing for the edge case was probably more dangerous than any real potential damage from the edge case itself, a paradigm that eluded even great engineers quite often even up to the end of the 2000s.

Every single "feature" I wrote into WWIV to thwart account hijacking or sock puppets or war dialers did very little to curtail the encroaching troll taint, while frustrating the few hundred engaged users I still had left. What they needed was a moderation system based on positive karma and what I gave them was more incentive to go to AOL. I had all of the data that should have led to a better decision, I'd just never thought about trust systems or even data before. It really is true that you're never know how something you make might inspire someone else.

So I take my wikis very, very seriously. Stack Overflow of course sucked me in (where back in 2009 I theorized the existence of the product that I now work for. And it's not just my penchant for completely unhinged documentitive altruism; I really get into things that start as a sandbox where I can build a unique platform to teach something.

And now that I've outed myself as a connoisseur of the ways of the WikiWikiWikipedian, I want to talk to you about something that I've really enjoyed using - Docusaurus, because I'm once again really inspired. I'm the nerd that would volunteer to set up your Wiki or Trello board just for the thrill of doing it, and Docusaurus' feature list pretty much gestured at all of me.

What do I like, more specifically than "pretty much everything?"

It was the practical ramp to React that I'd been looking for.

I love code sandboxes and I'm definitely a sucker for any interesting live demo where I can get a quick dopamine rush from doing something neat, but I'm very slow to actually learn things that I don't have an immediate, practical reason to use. I'm a systems programmer; I work on things like device drivers, file systems, embedded devices that have really tiny memory ceilings and custom shells. I don't really work on front-end code unless I need to whip up some kind of admin interface, or a .. you guessed it .. wiki or documentation site of some kind.

With Docusaurus, you're strongly encouraged to create reusable React components to deliver great UX and keep the site easy to maintain. By its design, you quickly figure out how NOT to end up with a global scope full of spaghetti and debt you need to pay down before you can even think about handing it off to someone else to work on.

It's the first documentation platform where I ended up with the same installation that I started with, without having to completely re-install it after "figuring out how I should have done everything."

It introduced me to MDX/JSX

If (like me) you're so busy Swimming in the C, you might not have heard about this really cool thing called MDX. Being able to very easily bring components right into portable markdown documentation opens up so many doors to making a better experience.

Just something like easily adding tabs to admonitions can make a document easier to read. You're able to stop publishing great walls of well-formatted text and instead create things that people will enjoy interacting with, including live codeblock support that I want to play with much sooner than later.

It's Extremely Contributor-friendly

I managed the internationalization project for Stack Overflow into Portuguese, Russian, Japanese and later Spanish. It was one of the most difficult things I did there.

Docusaurus' i8n workflow is exactly the right level of simplicity. And, because Docusaurus encourages component thinking, you end up (by default) with a very efficient workflow, and you don't run into cases where translators lack context to transliterate. That's huge when you're asking volunteers to not just provide, but actually maintain translations.

Every page has a link where you can sign into Github (or wherever) and kick off a PR to correct a typo. There's no need for gatekeepers or complexity beyond the site maintainers themselves, and its simple to contribute a tutorial without knowing anything other than Markdown.

Accessibility Isn't Bolted On, It's Cooked In

Beyond great locale support, Docusaurus ships with a fully responsive theme for both light and dark mode that's easy to customize using traditional CSS or Infima. The people that are frequently tasked with writing technical tutorials aren't generally experts at publishing them in accessible ways. In order to maintain accessibility, it has to be there from the start and it has to be really hard to unintentionally break.

The site I'm launching at the end of this month will not just have dark mode without any shenanigans where an account is necessary to use it, it'll also have a convenient way to render content in the Open Dyslexic font.

I Don't Have To F*** With Tag Engines, Search Or SEO

If you know, you know. Implementing search and taxonomy is not a problem I'm interested in solving, so I greatly appreciate the fact that it's not a barrier here. I have seen great programming careers completely die after someone fell down a rabbit hole named search.

There's two forms of drilling down into content that really matter to developers, tags and search. Docusaurus has several great search options from Algolia to just integrating your own; my favorite is @cmfcmf/docusaurus-search-local.

Tags can be dynamically created in plain text metadata at the top of your articles or blog posts. Oh wait, that's right, it has a built-in-blog with feeds that can alleviate your life of dealing with Wordpress plugins.

And with official plugin support for sitemap generation and the usual Google website components you don't need to worry about it.

All Static - There Is No Database

That's right, production (including the search index) is statically-generated. I don't have to worry about migrations, scaling databases, backups, SQL injection (this doesn't mean I don't need to worry about getting p0wned, it just takes away one of the biggest surfaces) or forgetting to put a WHERE clause in an UPDATE statement.

That doesn't mean I can't pull in dynamic content or talk to web hooks or other nifty things. It just means I'm content to let the file system do its job and content to talk to it in Markdown. But just because it doesn't need a database by default doesn't mean it can't use one - again, components make tons of sense.

Rot-Resistant By Design

Straight-forward versioning is a very important feature especially when you're running a beta with weekly iterative releases. If your tech stack mostly involves extremely mature, well-tested and stable components then you probably haven't experienced a lot of things that undergo multiple complete redesigns in a month as you iterate on feedback from design partners.

Without this, you approach a launch where almost 70% or more of your documentation is probably no longer even relevant. Docusaurus also treats the next release like you treat the next sprint (if you use sprints), so it doesn't require mental contortion to keep stuff up-to-date in a way that also gives as much advanced notice of what's coming over the fence to your users.

And something really cool - Docusaurus validates all internal links with configurable behavior - you can either throw (default) and break the build if they're detected, or warn, and this behavior is configurable for HTML and Markdown syntax independently.

Static Pages & Marketing Friendly Features

Marketers and growth managers can use Docusaurus to create really nice looking landing pages for easy one-off experiments often without having to get a developer involved. Since you can send per-route custom headers, they can whip-up something in an hour or two to test on Twitter on a Wednesday afternoon just to get a feel for how a strong CTA should look, all while not creating any disruption on the documentation site.

They grab a template that contains Markdown and some React components like <IterateFeatureList /> or something, and fill in what they need with Markdown.

There's Like ... A Lot More To Like

I recommend just going through the manual and if you don't find at least five things to get excited about then I'm sorry that I've kept you so long, but I feel confident that anyone who has previously maintained complex documentation will at least not be sad that they looked.

I'm also doing this completely unprompted and I'm in no way affiliated with the project or Facebook in any way (you will not read flattering things about Facebook from me, to put it mildly). But the people that have put this together have really brought something to the table that I hope will help you, dear person that skipped or read this far, up your knowledge-sharing game.

 
Share this