I’m happy to announce several updates to the Workers Docs that will allow you to take full advantage of our Workers platform. We integrated your feedback about the Docs user experience and design. We reorganized and reformatted all of our content. We upgraded the Docs engine to add new UI components. The documentation is now intuitive to navigate and the content is now easy and enjoyable to read.
You can find our new and improved documentation site here and can find the docs engine on our repo.
We hope this creates a better developer experience for you and makes the Docs more approachable to beginners. We plan to use our work and improvements for the Workers Docs to revamp docs for other Cloudflare products too.
Here’s a more detailed breakdown of the Workers Docs update.
Content Organization: We reorganized site content into four categories to make it easier for you to read and find content: Tutorials, How-to guides, Technical reference, and Learning. The new content structure is heavily inspired by Divio’s documentation system.
The tutorials section groups together step by step guides for building a specific project on Workers (e.g. teaching a beginner how to cook). The how-to guides are a collection of examples to help developers understand and implement a specific feature of the Workers platform (e.g. a recipe in a cookbook). In the new Docs, the how-to guides section is split into the examples and starters pages. You can think of the examples as code snippets and the starters as fully completed and cloneable projects. The technical reference is a descriptive breakdown of each technical component for Workers (e.g. a reference encyclopedia article). In the new Docs, we decided to split the Reference section into three groups for Platform, Runtime APIs, and Wrangler documentation to make content easier to find. The learning section builds understanding for a specific topic or concept about the Workers platform (e.g. an article on culinary social history.)
The key insight is that by breaking content up in this way, each of the four types of documentation only has one job so it can really nail it. Plus, it makes it easier to find what you are looking for.
Improved Formatting: We added more structure and detail to our content. Here are a few examples. First, reference pages like the one for Request class now give more context with a background section explaining use cases and tips on how to use the class. We also added a table of contents to the right sidebar to make browsing through a page much easier.
We also cleaned up the formatting for content such as class breakdowns. This used to be done through chunky paragraphs of text. In the new Docs, each variable and parameter is listed and explained with plenty of whitespace for readability
Similarly, we have improved the formatting for command breakdowns which used to be tables. It’s now easy to read through with the same list based format for class breakdowns.
Redesigned Pages: With our Docs engine rewrite, we added new UI components and created new page designs. For instance, with the examples page, we added tags so you can sort by category. Also, the entire layout has been improved to make it easier to read and understand each example.
Another great example is the tutorials page. We updated the page to show the difficulty and length of each tutorial. This should make the tutorials and learning how to develop on Workers more approachable for beginners. We also added new tutorials such how to manage multiple Workers projects with Lerna.
Accurate Search: We updated the design for our Algolia docs search. The text is now easier to read and the results are prioritized better than before.
Dark Mode: You can now customize the Docs to your liking and switch between light and dark mode. We designed these two themes to be really easy to read and visually appealing.
I hope this update makes using the docs a better experience for you. We have more updates planned and are always looking to improve. Please feel submit an issue here if you have any feedback.