How is it better? (I read the blog post [1], as a technical writer I'm curious to hear people's first impression about which changes are most impactful)
Yep, also interested in this. I'm writing and managing (among other things) the team at https://dvc.org/doc and had a lot of discussions like "How do we name and structure the high level navigation items"? From what I read in the blog post (and even considering how much the need to explain the change) this split `Tutorials, How-to guides, Learning` is still confusing to me, to be honest. So, would be great to get more opinions.
(@kaycebasques cool stuff with Lighthouse and other docs, btw!)
We also published as part of this release some documentation for the so-called “Docs engine” which powers these new docs, which may somewhat answer this question.
(Note: They currently live within the Workers docs site for now but will get a proper home soon.)
With respect to the information architecture and content design, much of that is discussed in the Contributor’s Guide [1] and Docs-flavored Markdown [2] pages.
The very short version is that we borrowed many ideas from Divio’s documentation system [3], which recommend dividing your content into four distinct buckets: Tutorials, How-to Guides, Explanation, and Reference.
The layout and visual design were inspired by dozens of other docs sites we tested and studied, stealing the best ideas we could from everywhere we looked.
It’s also worth noting that the Cloudflare Workers docs have been open-sourced for over a year now [4], and these new docs (as well as the new engine which powers them) will continue to carry the same license. Contributions are welcome and we’re hopeful and excited to see further uses of the docs engine over time.
Fellow docs person here. Really like the new design—both in terms of information architecture and actually browsing the site! It looks like your docs engine is based on Gatsby. I'm looking into replacing our current static site generator, and Gatsby's near the top of the potential list.
I haven't dug into the repo yet, but building your own docs engine atop Gatsby seems like it would require a lot of additional config. Any major things you needed to address that Gatsby couldn't do out of the box? And when you say further use of the docs engine, are you open to other organizations using/tweaking it?
Gatsby is pretty powerful but also quite complicated and has a fair amount of issues to deal with.
For example it was pretty unergonomic to set up support for deploying to a `pathPrefix` [1] while retaining the ability to develop locally [2].
Nevertheless, we were able to make it work and have been relatively happy with Gatsby overall.
Absolutely! The docs are dual MIT and Apache licensed [3] so have at it. One note: we have not yet completely teased apart the so-called “engine” from our particularly implementation itself. This is something we’re planning to do, in part because we need to to support our other docs sites. You may find it easier to work with once we’ve done that. That being said, you can also just fork the repo, change the content and branding, and things should mostly “just work”. Of course if you run into issues along the way, we’d be glad to have contributions back to the project itself. Good luck!
[1] https://blog.cloudflare.com/new-and-improved-workers-docs/