Blueprints developer documentation

[adamziel]

Let's provide developers with ample examples on how to build Blueprints. One outline is proposed in WordPress/blueprints-library#64

[bph]

How would you want to keep the two places of documentation in sync: Community site and Developer Playground docs? Is there a way to use Docusaurus to deploy selected content to two (or more) sites?

Docusaurus allows for Document versioning. I do a little research on how that works maybe that's the solution.
Or maybe Multi-instance is the right way to go

[adamziel]

How would you want to keep the two places of documentation in sync: Community site and Developer Playground docs?

@bph I'd make the community space the canonical source of truth about Blueprints and remove them from the Playground docs entirely. There would be links, but no content duplication.

More context is that Blueprints are branching off to a separate repo anyway and will run not just with PHP.wasm in Playground, but also with regular PHP and WordPress core. It makes sense to have a dedicated space for the documentation.

[adamziel]

Related and relevant:

• https://make.wordpress.org/meta/2023/11/22/plugin-directory-preview-button-revisited/
• https://developer.wordpress.org/plugins/wordpress-org/previews-and-blueprints/
• https://meta.trac.wordpress.org/ticket/7487
• Add a draft page for Previews and Blueprints developer-plugins-handbook#5

FYI about this issue @tellyworth

[ironnysh]

@adamziel, would it still be based on Docusaurus? I wonder what the WooCommerce team is using for their cool new docs site.

[adamziel]

@adamziel, would it still be based on Docusaurus?

@ironnysh good question! Docusaurus is neat and provides a lot for free – from light/dark mode, syntax highlighting, algolia integration, ease of autogenerating docs and including interactive examples.

The only downside is the challenge with bringing that content into developer handbooks on wp.org. Perhaps if there was a separate, Blueprints handbook? I kind of dislike the custom tooling used to build these docs pages and would like to minimize their use as they tend to take time to set up, break, and require patches.

I wonder what the WooCommerce team is using for their cool new docs site.

CC @shaybanshee @JacklynBiggin on any insights about that.

[adamziel]

@flexseth also shared an interesting idea to build the documentation in Playground – it nicely tie with a thing that @ellatrix built to use .md files as WordPress database.

[ironnysh]

I kind of dislike the custom tooling used to build these docs pages and would like to minimize their use as they tend to take time to set up, break, and require patches

Totally agree (that's why I asked 😉).

I think that one of the most important parts that would help push this forward is the builder. Take tools like Swagger or Postman—the ability to do "live" prototyping and save/export the results is their main attraction. DX is king 🤓

a thing that @ellatrix built to use .md files as WordPress database.

🤯 Is it public?

[flexseth]

I think that one of the most important parts that would help push this forward is the builder.

There's a project in the works to link an individual docs page to block markup that can be spun up using a blueprint. The contributor can then update the docs, and submit a PR back to the repo where the docs exist. All with the click of a button!

[ironnysh]

There's a project in the works to link an individual docs page to block markup [...] contributor can then update the docs [...]

Are you talking about this one?

I was referring to the Blueprint builder, the browser-based JSON editor.

To clarify, my comment was less about the documentation tooling and more about developer tools (see @adamziel's initial statement above):

Let's provide developers with ample examples on how to build Blueprints

[adamziel]

🤯 Is it public?

https://wptavern.com/blocknotes-app-runs-wordpress-natively-on-ios-now-in-public-beta
https://github.com/ellatrix/blocknotes/

[adamziel]

I think that one of the most important parts that would help push this forward is the builder. Take tools like Swagger or Postman—the ability to do "live" prototyping and save/export the results is their main attraction. DX is king 🤓

Today there's a JSON builder and this "export as a Blueprint" plugin. Do you mean a UI Blueprints builder where you'd assemble blocks? Perhaps literal, Gutenberg blocks even?

[flexseth]

Do you mean a UI Blueprints builder

I've been looking into making something like this for the block editor.

After April 18th might have a little more time, going through all of the docs has been very helpful to see how it would need to be built.

Don't want to go into too much detail here to keep the issue on track, and closer to getting closed out at some point :)

[ironnysh]

Do you mean a UI Blueprints builder where you'd assemble blocks? Perhaps literal, Gutenberg blocks even?

You're like 12 steps ahead of me ;-)) I meant improving the existing JSON builder. Basically bringing it from WIP/MVP mode to V1.

Joost's plugin is very promising, but it'll be nice to have some control over what's "recorded".

[adamziel]

@ironnysh you've inspired me to fix the Blueprints builder: WordPress/wordpress-playground#1284

It's still rough on mobile but at least it's going to be reliable once that PR is merged.