How Deno's documentation is evolving

Documentation is a critical part of the experience of using a tool or service. As developers, we often depend on docs to help us discover a tool’s capabilities or to teach us how to use its features, and the ease (or difficulty) with which we find what we’re looking for can inform our opinion of the tool itself.

Making good docs is a big task, but an important one.

With that in mind, we’re on a constant journey to improve our docs. Deno is a big project, with a large surface area, so we have plenty to do, and thankfully, we get great help and feedback from the community.

Here are a few things that we’ve done to improve our docs lately, and some things we have planned for the future.

Better organized examples

Previously, our examples were spread around the docs site and located within different sections and products. That was fine if you knew exactly what you were looking for, but made it hard to discover examples and references.

Now all our examples are categorized and organized, in one place. If you prefer to learn with videos rather than code examples, you can filter your view, but you don’t need to go hunting around our growing docs site or blog to uncover the examples. The examples page is the place to go, and as a sign of how useful we think this is, we added it to the global navigation of the docs site.

More video examples

For those who prefer to learn by watching rather than reading, we added a set of videos to introduce concepts and techniques for working with Deno. As short, digestible videos, these proved popular and we’re keen to add more. Let us know if there are particular topics you’d like to see. We welcome your feedback and would love to address the gaps that matter most to you.

Since adding videos to the examples, we’ve heard from some folks that they prefer to read than to watch, so we’ll be adding transcripts to these videos and making sure that there are equivalent text-based tutorials or examples. We want the content to suit as many learning styles as possible.

Feedback and suggestions

In addition to chatting with us on the Deno Discord - where we even have a dedicated channel for discussing documentation - you can now provide feedback directly on our docs site. Each page features a feedback widget where you can let us know if the content was helpful and share any details or suggestions for how we can improve.

All the feedback is collected and reviewed each week in our docs planning meeting. We’ve had some excellent suggestions already, and these all help to make the docs better for everyone.

Simplified sidebar

Sometimes removing things can give the best improvement. By collecting our examples in one place, we’ve been able to remove a lot of items from the sidebar navigation. This should help those exploring the site and looking for something specific, while not sacrificing easy access to the examples.

Contrast and legibility

We discovered that some of the colors we use around the site can, in some combinations and font sizes, result in poor contrast. We made some small but important adjustments to keep things legible in both light and dark themes and are much happier with the result.

More documentation in Code

Some parts of the docs site, such as our API reference section, display content generated directly from the source code. Where the source code includes descriptions, examples, and references, these are used by our site generator to create and populate the pages.

We’re actively working to add more and more content this way, which not only improves the docs, but also adds useful documentation directly into the open source code it is documenting for a double win.

Better mobile navigation

The vast majority of the visits to our docs happens on a desktop rather than a mobile device. But we were still cross with ourselves when we spotted a silly oversight in the primary navigation when viewed on mobile. Some of the primary navigation to other sections of the docs site were not visible. Not ideal!

We’ve fixed this now with some improvement to the global navigation and better consistency around the site. Come on in to the other parts of the docs site, mobile friends!

A new site generator

Last year we adopted the use of a new site generator to build our docs. We selected Lume as the tool to improve our flexibility and development velocity.

Lume is emerging as a very capable and elegantly designed site generator. It shares some principles that will be familiar to fans of Astro, Eleventy, and Jekyll, and gives excellent control over what code you generate and ship to your users.

With a well-curated set of plugins which extend the core features, Lume gives lots of flexibility over templating, build pipelines for CSS and JavaScript, and has thoughtful APIs for sourcing and querying your data.

Are we done yet?

Nope. While we continuously work to refine and improve the content in the Deno docs, we’ll also keep on working on the user experience and discoverability. We don’t expect that we’ll ever be truly finished, but hope we can keep on iterating and improving things.

We’re grateful to everyone who contributes feedback, suggestions, and even examples to the site. Thanks for all your efforts. We’ll keep working too.