WordPress Playground documentation

[adamziel]

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?

[zzap]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[adamziel]

Documenting the recent meeting on the #docs slack channel:

• Could this format work for Playground docs? Let's explore. https://github.com/WordPress/Advanced-administration-handbook It's built from a manifest file here https://github.com/WordPress/Advanced-administration-handbook/blob/main/bin/handbook-manifest.json
• Adam's ideal scenario is for te doc to live in the WordPress Playground repo – that’s the easiest way to keep it in sync with the code. Adam is also planning to build some automated checks to make sure it stays up to date.
• @javiercasares thinks it may still be possible to publish Playground docs as a WordPress.org Handbook, even if that would require a few customizations on the wp.org side.

[javiercasares]

Using the actual https://github.com/WordPress/wordpress-playground/tree/trunk/pages, and planning a site like https://developer.wordpress.org/playground, it should be possible to sync automatically the actual documentation.

If Documentation will be responsible for this, we can prepare a little roadmap on what we need and how to do it and start working.

I'll be on WordCamp Europe (Contributor Day) so we can check that.

Just coming to my mind, may be this:

— Create the “manifest file” (usually inside a /bin/ folder in the documentation -/pages/- folder)
— Check that when the pages are generated (if automatically with external software), that folder won't be destroyed. If they will be updated manually won't be a problem.
— Ask for https://developer.wordpress.org/playground as a site like the Advanced Administration. Set it up in a private mode, at first.
— Ask Meta to sync the manifest file with the new site.
— Check the content and fix whatever may not be perfect ;)
— Launch the site.

I can help with anything you require. Ping me when your next meeting is and we can see what is needed.

[adamziel]

Thank you @javiercasares!

The documentation site got refreshed to use MarkdownX – this way it supports interactive code examples. It still has the same HTML-based API Reference as before. The files now live in https://github.com/WordPress/wordpress-playground/tree/trunk/packages/docs/site/docs.

Let's definitely get in sync on WordCamp Europe how to best proceed – I'm not quite sure. Using Markdown instead of MarkdownX would reduce the usefulness of the documentation quite a bit (no more live examples). At the same time, using the generated HTML might not work on wp.org and would also yield a handbook that looks unfamiliar and differs from all other handbooks.

Then, I'd like to eventually support live code examples in all WordPress.org documentation resources. Perhaps Playground would make a good pilot project for that?

[javiercasares]

See you at WordCamp Europe. I'll be at the Hosting Table, so, look for me :)