Aging technical documentation is a problem. Your customers lose trust in you when your public advice doesn't match your actual product. If users and prospects don’t have the self-serve help they need to be successful, they’re gonna bail for someone else.
Not to mention, developer docs are a product and are one of the best touch points you have with the software engineers of the world.
You should be prioritizing docs. So should we.
If our docs could talk, I know what they’d say. I’m imagining sitting with them in a warm, cheery therapy room, having an enlightening heart-to-heart.
The glow of an incandescent bulb tries to soften the situation. Still: there’s an uncomfortable silence. I know something’s wrong. I cross my legs and patiently wait.
Finally, after a long pause, our docs begin to open up:
“It’s just… in a world of billions upon billions of others just like me, it’s easy to feel insignificant. Forgotten. Neglected. You know… distant. Sometimes, everything seems to be moving so fast that it’s impossible to keep up. I look at myself and am blown away by how quickly I’ve aged.
I know everyone is busy, but I wish someone would think of me. Make room for me. Prioritize me. Check in occasionally to see how I’m doing. Take a weekend off to just sit with me and read. Give me some feedback on where I need work. Compliment me! Gosh, just a little recognition. Is that too much to ask?"
Turns out we have a lot in common with our docs.
This past week, we set off—together—to finally do something about it.
What to do when you(r docs) need attention
When we shipped our complete docs rewrite early last year, there were clear improvements over the previous iteration. People were stoked. Customers would regularly compliment the work we did. We put a lot of time and effort into making our docs great and people appreciated it.
The truth is… we haven’t heard that same feedback in a while. As our products grow in capability, so too do they in complexity — and this also means more documentation. Documentation that, while helpful, is thrown onto the pile, represented using the same framework that we’d introduced years ago; a framework that was meant to organize and present a younger, less mature version of Mux.
It’s not just the complexity of the content. The same thing was happening under the hood, too. Just like we were throwing content on the pile, we were slinging code onto the pile. New guide features, tweaks to the guide nav to support our growing information architecture, and don’t even get us started on the hairball of code underneath search.
This probably isn’t a new story to you. Technical debt and content debt accumulate when you don’t take time to pay them down. The folks charged with protecting the Developer Experience at Mux, some of whom are writing this blog post, got pulled by other priorities and didn’t make time to pay that debt down.
Over the past year, it became clear. This wasn’t working. We needed to do something about it.
And that’s how DocsJam 2024 was born.
Recognize the issues at hand
The first step towards fixing a problem is admitting that there’s a problem to begin with. Adding more content and features had magnified three issues that we felt we needed to address:
- our search UX was clunky and returned poorly ranked results
- our guides were tough to navigate
- our recipes, workflows, SDKs, and open-source repositories were difficult to discover
Get in a room and hash it out
Like many problems we face, the most effective way to tackle this issue was to confront it head on. Dave fired a Slack message to Matt and confessed to him what we were up against —and suggested that the way we were going to fix it was by sending an engineer, a designer, and a hybrid-writer to the mountains for a week.
The mountains? On the company dime? Are you serious? Isn’t that just handing your employees a vacation trip for rest and relaxation?
Nah. Don’t let your imagination run wild. Instead, take this note: surrounding yourself (or your employees) with whatever is most inspiring will produce some of your most impactful work. Try it out.
Getting in the same room together short-circuited countless Zoom calls and back-and-forth feedback loops. Don’t get us wrong, at Mux, we support remote-equal culture. I truly believe that the best way to protect my focus and find deep work is through uninterrupted time in my modest home office. But there’s always going to be something energetic about being next to your colleagues, letting your imagination fly, and watching your work come to life in real-time.
The trip itself wasn’t particularly posh; we’re three homegrown Midwesterners all raised to pinch pennies. Also, Rob, our Creative Director, is a recovering ski bum. Under his patrol, we shopped at the local Fresh Market and ate a frozen pizza for dinner, bagels with cream cheese for breakfast, and deli meat sandwiches for lunch. 3 people, 3 meals, $67.73. Not bad.
We’d posted up at a kitchen table — three laptops, a Bluetooth speaker, and a bowl of chocolate peanut butter eggs — and picked a specific topic to focus on. We debated through the pros and cons of different approaches, ran past different user journeys and scenarios, and reviewed our docs from the perspective of our customers.
It was clear what had to be done. Now it was time to do it.
Put in the work to get better
The ideas flowed like the enduro bikes down Tommy’s Two Step trail. Rob whipped up countless Figma comps and got immediate feedback about what needed changed. Dar turned those previews into code and hastily marked the subsequent pull requests as Ready for Review. Dave shattered Dar’s heart and reported the numerous bugs that sent him crawling back to the IDE.
It started with adding tables of contents to our docs. We previously used a concept called “steps” to help users navigate the headers of our guides. Steps are a curated list of headers meant to help users jump to the juicy parts of guides. However, steps require maintenance. As our product grows and our guides grow, authors must constantly revisit them to make sure they’re still providing utility and not just growing into… well… something like this.
While we still believe steps are a helpful way to introduce folks to some guides, we decided that most guides would be better served with a lower-tech, lower-maintenance solution. That’s right, the table of contents. We did it, folks. We discovered a writing technique in use for literal millennia. And, at the same time, we audited each and every one of our guides to make sure that the headers actually said something useful so the table of contents could be as effective as possible.1
We’ve been talking about a table of contents for literal years. And now, in just a one long day of work, we had a PR. As we worked late into that first night, we slowly released our grip on the frustration with our old docs, feeling it fade away into the starry September night.
We woke before sunrise and hiked up the hill behind the hotel, kickstarting our ideas, conversation, and blood flow, carving switchback after switchback, the elevation ruthless to Dave’s Midwestern lungs. This was the right way to start the day.
We next turned our sights to search. We’ve known for a long, long time that our custom search component wasn’t cutting it:
Over time, we tried a few things to fix it, but we kept running into two fundamental issues. First, our product has been maturing and growing. With more guides and references to cover, there’s just more signal and noise for every search query. Second, we had over 2000 lines of search and indexing code, split over all sorts of components and contexts. We knew what kind of changes we wanted to make to improve our search experience. It just always ended up being a bigger project than we wanted to tackle.
Enter: Algolia DocSearch. It’s hard to admit that someone else can do your job better than you can. But, when surveying our favorite search experiences, we found time and again that DocSearch was under the hood. There are times when writing your own solution can give you a competitive advantage. This is not one of those times. So we threw out our old solution and integrated theirs.
There’s still room for us to improve our search results. But at least now, when we do, we’ll be standing on the shoulders of giants rather than wading through mucky, custom legacy code.
As our final day in the mountains dawned upon the autumn-kissed aspens and Dar drank deeply from his Pumpkin Spiced Latte, we turned our sight to one last problem. The team has published so many community projects over the past year: first-class support for Next.js, a video migration tool, brand new SDKs, an abundance of helpful videos, and AI workflow how-tos, just to name a handful. But the only way you’d ever know is if you happened to catch the blog post or read a newsletter at the right time. That’s not right.
Rob put some quick thought into the various ways we could resurface these projects so they could live on and be discovered for years to come. We carved out a new section on the docs homepage that can capture content published elsewhere, but might be considered docs-adjacent. This includes dev chats hosted on our YouTube channel, technical blog posts, and a smattering of our open-source initiatives. If there in an educational component to the content, it can live here.
At the end of day three, we stood back to assess our work. 3,820 lines of code added (and 4,186 lines removed).2 20+ design iterations. 237 files touched. A memoir of a blog post. And a docs codebase and DevEx squad that once again felt refreshed and alive.
There was only one way to celebrate the success of DocsJam™ in the Utah mountains. For us, strapping on our hiking boots and hitting the trail was the perfect way to connect and think through some of the challenges we were facing.
At times, the conversation was gritty, requiring critical thought and lively debate. But other moments were simple: a pause to absorb the view, inhale, to be inspired by the bigger picture, to feel grateful that we were together, here, now, in good company at a great company, growing, working towards a collective mission.
Be a good friend. Check in on your docs.
Have you checked in with your docs lately? What about your coworkers? Maybe it’s time. Give them a call (and perhaps a little love). You’ll be better off for it — and so will your customers.
If you’d like, you can see our refreshed docs in action. Give them a read. Drop us a note using the feedback component at the bottom (we read every single one). Maybe you’ll be inspired. And if there’s more we can do to make your experience with Mux even better, you know how to reach us.
