undefined | Better HN

0 pointsadamschwartz5y ago0 comments

(Designer of the docs)

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.

https://developers.cloudflare.com/workers/docs-engine

(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.

[1] https://developers.cloudflare.com/workers/docs-engine/contri...

[2] https://developers.cloudflare.com/workers/docs-engine/docs-f...

[3] https://documentation.divio.com/

[4] https://git.io/JJAWP

(edit: formatting)

0 comments

itmightbecody5y ago

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?

adamschwartzOP5y ago

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://git.io/JUJsy

[2]: https://github.com/gatsbyjs/gatsby/issues/16040

[3]: https://github.com/cloudflare/workers-docs-engine

j / k navigate · click thread line to collapse