DEV Community: Digital Speed

Choosing Your Documentation Tooling: A Practical Guide

Mike Elsmore — Tue, 27 Jan 2026 16:47:56 +0000

In our previous post on Developer Experience, we touched on documentation being one of the core pillars of great DX. We mentioned treating your docs as a product rather than a necessary evil, and pointed towards the docs-as-code approach. But we didn't dive into the specifics of what to actually build your documentation with. So let's fix that.

The Landscape

There's no shortage of documentation tools out there, and honestly, that can make the decision harder rather than easier. After working with various clients and our own projects here at Digital Speed, we've found ourselves reaching for a handful of tools repeatedly: Docusaurus, VuePress, Redocly, and Fumadocs.

Each has its strengths, and sometimes the best solution isn't picking one – it's knowing how they can work together.

Docusaurus

If you've spent any time in the open-source world, you've probably read documentation built with Docusaurus. Meta's documentation framework has become something of a default choice, and for good reason.

Docusaurus is React-based, which means if your team already lives in that ecosystem, the learning curve is minimal. It handles versioning out of the box (a genuine lifesaver when you're maintaining multiple API versions), has solid search via Algolia integration, and the plugin ecosystem is mature enough that most common needs are covered.

Several members of the team here at Digital Speed have used Docusaurus extensively, and what keeps us coming back is the balance it strikes between flexibility and convention. You can get something professional-looking deployed in an afternoon, but you're not boxed in when requirements get more complex down the line.

The main consideration? It's opinionated about structure, which is actually a feature if you're starting fresh but can be friction if you're migrating existing docs with unusual organisation.

VuePress

For teams in the Vue ecosystem, VuePress is the natural counterpart to Docusaurus. It's lightweight, fast, and the Vue-powered theming system makes customisation straightforward if you know your way around Vue components.

VuePress 2 (the current version) has matured significantly and offers a clean developer experience. The markdown-centred approach means your content stays portable, and the plugin architecture is sensible without being overwhelming.

We've seen VuePress work particularly well for smaller documentation sites or teams who want something less heavyweight than Docusaurus. If you're documenting a Vue-based library or your team simply prefers Vue's patterns, it's worth serious consideration.

Redocly

Now we're getting into more specialised territory. Redocly is laser-focused on API documentation, specifically OpenAPI-based docs. If you're building products with REST APIs (and let's be honest, most of us are), Redocly deserves a look.

The open-source Redoc renderer produces three-panel API documentation from your OpenAPI spec. It's the kind of documentation that makes developers actually want to integrate with your API. We've used the open-source version at Digital Speed and found it does exactly what it promises with minimal fuss. The only issue with the open-source version is you're pretty much locked in to the limited out-of-the-box styling and theming options, so you can't expect to customise the design much.

Beyond the renderer, Redocly offers a CLI for linting your OpenAPI specs and a broader platform for teams who need more – but the open-source tools alone cover a lot of ground.

The key thing to understand about Redocly is that it's not trying to be a general-purpose documentation platform. It's purpose-built for API reference documentation, and it excels at that specific job.

Fumadocs

Fumadocs is the newer entrant here, built specifically for the Next.js ecosystem. If you're already running Next.js (and plenty of teams are these days), Fumadocs integrates naturally into your existing setup rather than being a separate concern.

We've recently started using Fumadocs at Digital Speed and have been impressed by how it handles the basics. The search works well, the theming is highly customisable and clean, and it doesn't fight against Next.js conventions – it embraces them.

It's worth noting that Fumadocs is younger than the other options, which means the ecosystem is smaller and you might occasionally hit edges that haven't been smoothed yet. Additionally, the documentation is directly tied to Next.js versions and isn't versioned itself, so you might not be able to find documentation for older versions of Next.js. But for Next.js teams, it's a compelling option that's maturing quickly.

Using Tools in Concert

Here's where it gets interesting. These tools don't have to be mutually exclusive.

A pattern we've seen work well is using Docusaurus (or Fumadocs, depending on your stack) as the primary documentation platform for guides, tutorials, and conceptual content – then embedding Redocly-generated API reference documentation within it.

This gives you the best of both worlds: a flexible, customisable platform for your narrative documentation, paired with purpose-built tooling for your API reference. Your developers get a cohesive experience, but you're using the right tool for each job.

The integration is typically straightforward. Redocly can generate static HTML that you host alongside your main docs, or you can embed the Redoc React component directly if you're in a React-based framework.

Making the Choice

So how do you actually decide? A few questions worth asking:

What's your team's existing stack? If you're React-heavy, Docusaurus or Fumadocs (for Next.js specifically) will feel natural. Vue teams should look at VuePress.

Do you have OpenAPI specs to document? Strongly consider Redocly for that portion of your docs, even if you use something else for the rest.

How much customisation do you need? All of these tools are customisable, but they sit on a spectrum from "works great with defaults" to "expects you to build on top." Know where your needs fall.

What's your team's capacity? A smaller team might prefer something lightweight like VuePress or Fumadocs over Docusaurus's broader feature set.

Conclusion

There's no single "best" documentation tool – there's only the best tool for your specific situation. What matters more than the specific choice is that you make a choice and invest in your documentation as a proper product.

We'll be covering more specifics around SDK development and API documentation in upcoming posts. In the meantime, if you're struggling with your documentation strategy or need help implementing any of these tools, we at Digital Speed are happy to chat.

After all, great documentation is just another way of helping developers get things done.

The Differentiator Between B2B products: The Developer Experience

Mike Elsmore — Wed, 21 Jan 2026 12:00:00 +0000

Here at Digital Speed we are active users of AI within our day to day, a lot of us enjoy using Claude Code as part of our tool chain and we even use Spec Kit within some projects, and we can see how it has improved our pace and work.

But the velocity created by the tools we have to hand mean that everything is starting to feel a bit samey when integrating products together. So that’s the biggest separator between the products we’ve used recently? The Developer Experience, otherwise known as DX or DevX.

What is Developer Experience?

Most people see DX and think UX, which is close but not quite right. The dictionary definition of Developer Experience from Wikipedia is:

"Developer experience (DX) is a user experience from a developer's point of view. It is defined by the tools, processes, and software that a developer uses when interacting with a product or system while in the process of production of another one, such as in software development.[23] DX has had increased attention paid to it especially in businesses who primarily offer software as a service to other businesses where ease of use is a key differentiator in the market."
Some people on Wikipedia - https://en.wikipedia.org/wiki/User_experience#Developer_experience

A much nice definition is this quote:

"DevX is about creating frisson with your product. It's about creating thrill, feelings of excitement, and enabling and empowering developers to believe, 'Hey, I can do that.'"
Salma Alam-Naylor, @whitep4nth3r

If you want to watch a video covering the subject, our very own Mike Elsmore gave a talk at WeAreDevelopers. But what are the core things to consider when thinking about your product's Developer Experience?

Documentation
Tooling
Support

We’ll be covering some of these specific topics in follow-up posts, but for now here is a quick overview of the things to consider.

Documentation

When moving at speed, most organisations don’t have time to keep documentation up-to-date. The biggest advice that can be given here is treating your documentation as a product, rather than as a necessary evil.

If you are a tech first organisation, then one of the best things that can be done is a shift to docs-as-code. An amazing article on this topic written by Joanna Suau covers all this in greater detail: how to adopt a docs-as-code approach for developer documentation.

As for what should be used for documentation, or what should be covered, this is very much dependant on the product. And we will cover this more in depth in a follow-up article. However, just as something to think about in the mean time if you are providing technology with an API interface that requires a complete reference and should follow a standard like OpenAPI Specification. On top of this a glossary of all possible errors from the API or tool should be available alongside it.

And the last things on documentation, make sure it’s written from the perspective of someone that has no knowledge or prior skills.

Tooling

When it comes to how developers interact with your product, it can differ widely. But the common consensus is to provide a faster and smoother way to integrate your product with whatever they’re building in whatever language or system they are building it within.

The most direct way, after documenting the basics for any interaction, is through an SDK. SDKs can consist of things such as API wrapper clients, to full CLI tooling, but they all contain the pieces to simplify integrating things such as authentication/authorization. We’ll cover more of the specifics of how to build out SDKs (primarily Client Wrappers) in a follow up post, but for now I’ll present some of the best examples.

The Fly.io CLI (otherwise known as flyctl), is a great example of a command line interface that would allow someone to interact with the product directly or even script out into CI/CD flows.

A great example of a full-service SDK has to be the AWS SDK (in any language they build for). Considering how vast the product array is across the AWS portfolio, it’s consistent and easy to navigate with a lot of documentation and all sorts of helper functionality on top of the APIs.

And now in the age of AI, it’s worth considering MCP servers and the likes, just as a means to allow developers to build agents to interact with your product. Or at the very least, for AI tooling to have a better understanding of the product when developers are doing research or solving a problem.

Support

Unfortunately, this one comes very much down to business and financial budgets. Support tooling and time to manage supporting your end users is a large part of great developer experience. No matter how much documentation you have, or tooling you provide, developers of different skill levels will have issues or edge cases to contend with.

The only suggestions here are, if the product and budgets are small (or non-existent) then allow and enable the community of developers to support and help each other. Provide a place like Slack or Discord for developers to find other developers that may know what they don’t, and at the very least provide a searchable location for Q&A such as discourse or GitHub Wikis.

Conclusion

Developer Experience is more than just these three things, as it can include the onboarding process or even the marketing material that developers consume. But they’re less focused on the problem of solving how developers use the product day-to-day. Another quick quote about what DX is and why it’s great:

"Helping developers get sh❤️t done."
Salma Alam-Naylor, @whitep4nth3r

If you or your company need help with Developer Experience, we at Digital Speed are more than happy to discuss your needs and see how we can help. And if we can’t help you directly, we can recommend organisations to work with that could help.

Spec-Driven Development: The Future of AI Coding

Taylor Lindores Reeves — Tue, 20 Jan 2026 12:35:56 +0000

Our Approach

The engineering practices at Digital Speed have evolved over the years. But one thing that hasn't changed is our focus on writing high quality, maintainable code. And since the advent of AI and vibe coding, it's become far more important to ensure clean and maintainable code is being written.

What is vibe coding I hear you say? Below is a quote directly from Merriam Webster:

"Vibe coding is a recently-coined term for the practice of writing code, making web pages, or creating apps, by just telling an AI program what you want, and letting it create the product for you. In vibe coding the coder does not need to understand how or why the code works, and often will have to accept that a certain number of bugs and glitches will be present."

Vibe coding is inherently risky because, unless there's a significant amount of time invested in reviewing the AI-generated code, it's very likely to introduce issues. Not only that, but the code is harder to maintain and the transfer of knowledge is challenging at best. For those reasons, our team only used AI to write tedious refactors or edit inline code segments, as opposed to vibe coding full features. But times are changing.

This is where GitHub's Spec Kit comes in. This is an open-source tool that allows any developer to swap vibe coding with Spec-Driven Development (SDD). Now why is this better than vibe coding? It's because it forces everyone in a team to establish shared context before any implementation begins, which means AI agents and teams build exactly what was intended. By separating intent from code, we can avoid the chaos of assumptions and ensure every decision is explicit, reviewable, and easier to evolve. Dive into more detail about SDD in this blog post by Den Delimarsky, Principal Product Engineer at Microsoft's CoreAI division.

This fantastic tool is a game-changer. And it makes sense. We have learned a lot after building many products for our clients over the years here at Digital Speed. There's an industry best-practice behind every successful product launch, and it starts with creating detailed specification documents. This is what Spec Kit was designed to do.

Spec-Driven Development with Spec Kit is a feature-based approach to writing code, and it all starts with generating detailed documentation. The core concept is to produce enough accurate detail about intent so that the AI has the contextual foundation to build the feature correctly. The idea is to produce a set of files based on pre-determined commands. Those files are generated as markdown files. It's important they're generated in the following order as each prior step gives context to the next:

Constitution: defines the project constitutional guardrails. These are the non-negotiable principles that must be adhered to at all times.
Specification: build a specification document and requirements checklist based on your prompt.
Clarify: asks 3 to 5 clarification questions on the spec to help prevent ambiguities.
Plan: create a technical plan for the specification.
Tasks: break down the technical plan and the spec into a set of individual tasks.
Analyse: analyses the spec, plan, and task breakdown for any inconsistencies.
Checklist: create “unit tests for English” for your specification, enabling you to quickly find blind spots in your domain thinking.
Implement: implement the project based on all of the combined artefacts.

Clarify, Analyse and Checklist are intermediary commands we can run between each doc generation step which helps us to clarify, analyse and update the generated artefacts. This is outlined in the diagram referenced above.

Ultimately, you end up with a directory structure like this, alongside the rest of the files and directories for your project, in your codebase:

.specify
  memory
    constitution.md
  scripts
    bash
      check-prerequisites.sh
      common.sh
      create-new-feature.sh
      setup-plan.sh
      update-agent-context.sh
  templates
    agent-file-template.md
    checklist-template.md
    plan-template.md
    spec-template.md
    tasks-template.md
specs
  001-example-feature-one/
  002-example-feature-two/

And within the individual feature directories (which by the way, are also the name of the feature branch you are now working on - all executed because of Spec Kit) shown in the specs directory above, you'll have your generated files which typically look like this:

specs
  001-example-feature-one/
    checklists
      requirements.md
    contracts
      example.md
    data-model.md
    plan.md
    quickstart.md
    research.md
    spec.md
    tasks.md

The final step is to run the implement command and let the LLM go to work implementing the tasks created in the tasks.md file. But before that, we get our AI Agent of choice, we use Claude Code at Digital Speed, to use GitHub's CLI tool to create a Pull Request from our current branch 001-example-feature-one to main with a detailed description, to make sure that the effort is properly tracked and our entire team can view the spec documentation before implementation.

Once implemented, we're able to release this feature branch 001-example-feature-one onto our CI/CD pipeline to QA the results, and we've been having astounding results thus far.

If you are looking to bring spec-driven development to life in your own organisation, our engineering team can help you move from idea to production with clarity, pace and confidence. Reach out to us and explore how we can accelerate your next build or check out our services to find out more.