Welcome to the New faustjs.org

🎶 ...we've got fun and games... 🎶

Welcome! This project was several months in the making with WP Engine’s DevRel team leading the way and support from the Headless Open Source team that maintains Faust. 

TL;DR

Our goal in rebuilding the docs was to provide users with a clearer understanding of Faust, better documentation on how to use it, and better workflows for our teams to maintain the site and documentation. 

We accomplished these goals through:

1. Repositioning Faust.js as a “toolkit” rather than a “framework.”
2. Implementing the Diátaxis system to write documentation.
3. Open-sourcing the site.
4. Open-sourcing the documentation and moving the docs into the Faustjs code repository.

If you have any feedback or find bugs, please open an issue on the repository.

Repositioning Faust

The old positioning of Faust has been difficult to convey effectively. Faust wasn’t an alternative to popular frameworks like Astro, Nuxt, or Next.js but was, in fact, built on top of Next.js. Viewing Faust as a “framework” led many to think it competes against these other options rather than building headless WordPress-specific features on top of Next.js.

With this in mind, DevRel is repositioning Faust as “The Next.js Headless Toolkit for WordPress.” We believe this better communicates the role of Faust.js in the development ecosystem—not by competing with Next.js, but by enhancing it for WordPress.

Implementing Diátaxis

Documentation is hard. It’s also a product just as much as the actual code developers produce. We talked about the importance of documentation a lot in our recent retrospective post. The Diátaxis system provides a great platform for writing documentation and keeping it focused on the needs of the developers who use it. We believe this foundation provides Faust users with the best experience. 

The system also provides us, as the producers of this documentation, with a great way to think about the content we write, both in terms of our readers' goals and how to orient content toward those goals. 

Diátaxis has helped us organize existing docs into neatly categorized, clear, and concise documentation and highlighted areas where new documentation would be beneficial. We hope these changes improve your experiences using Faust.

Open-Source Code

All code that drives faustjs.org is now open source. 

We believe that example code is a powerful learning tool. We want to share our code so everyone can learn from how we build with Faust and headless WordPress. This also enables community contributions, which we welcome.

Docs With Code

“To dogfood, or not to dogfood,” that is the question—or “drink your own champagne,” if you will! 

We love the idea of using our own products because if it’s not good enough for us it’s not good enough for you—but we also don’t think all websites are equal. No software, WordPress included, solves every problem equally. In this case, we also believe strongly that documentation should live with code. Historically, in the name of dogfooding, the Faust docs lived in WordPress along with various pages and blog posts like this one. 

With the rebuild, new voices advocated making the docs available for community contribution and moving them into the Faust repo. This allows us to update the code and the documentation in a coordinated way, from a single, unified repository. We expect this to significantly reduce issues with the code and documentation becoming out-of-sync.

This also creates a standard workflow for contributing to docs. Just like code, anyone can contribute small or large changes to docs. We’ve added an “Edit this doc on GitHub” link to every docs page that allows the community to quickly submit PRs if they have any suggested improvements. 

While we no longer use WordPress for our documentation pages, it is still at the heart of our site, driving this blog and several other pages. This is a pattern we’re excited to show off. One powerful benefit of headless is that you aren’t stuck with a specific database or data source—you can cherry-pick the best tools for the job. In this case, we’ve chosen WordPress for publishing our blog, and Markdown for publishing our documentation.

The Show Goes On

We are really happy to share the new site, and many of you have already been providing feedback on the new documentation, pointing out bugs, and suggesting improvements. 

Thanks for the assistance and please keep helping us hone the future of Faust through the GitHub repositories (docs: faustjs or site: faustjs.org), or Discord.