The Ask

Let's create a comprehensive documentation for WordPress Playground. The existing one is brief and sometimes outdated. I posted a detailed outline here: WordPress/wordpress-playground#217

Where does the documentation live?

The documentation is currently published on GitHub Pages which conveniently couples it with the code – it's generated and published directly from the repository.

Technically, it lives in the gh-pages branch where it's built from:

• Markdown pages living in trunk
• The codebase, using a tool called Typedoc.

Typedoc is great. It outputs readable pages, cross-links specific API items together, and just works. In Gutenberg we use our own tooling that does neither of these things. Here's a discussion about migrating Gutenberg docs to Typedoc.

Where should the documentation live?

I recommend a separate static site regardless of the domain (Github.io works just as well as WordPress.org).

Why?

Typedoc outputs full HTML files, which makes integration with a WordPress-based docs site inconvenient. We could use github.io just for the API reference and move the rest to WordPress.org, but then we'd lose the valuable the ability to cross-link and cross-include parts of the docs. We'd also lose the potential to use MDX.

Questions

• Is this something we could collaborate on? Caveat: I'm on Sabbatical starting June 26th.
• What would be the next steps here?