Reorganise documentation

[chrisvanpatten]

This is the long-awaited reorganisation of documentation into three handbooks:

• Designer/Developer Handbook (Designer & Developer Handbook #11251)
• User Handbook (User Handbook #11252)
• Contributor Handbook

This is NOT READY FOR MERGE OR REVIEW. I hope this is ready to go… or close :)

Thank you ❤️

[chrisvanpatten]

So far this PR only moves files; I will be reorganising within files next, and hope to have this merge-ready ASAP as it's a big change that will impact a lot of things.

[chrisvanpatten]

Todo:

• Update manifest.json
• Update root-manifest.json
• Update all internal links

[chrisvanpatten]

I’m going to write a small manifest generator tomorrow (probably based on the one WP-CLI uses) so we can get those references updated, then do a final pass at internal links. I think we will have a first version ready for tomorrow afternoon, and I’ll file iterative PRs from there.

Really keen to get this first pass done and merged quickly to avoid any messy rebases/merges since it’s a fairly wide reaching PR 😅

[0aveRyan]

working on updating structure for developer docs per discussion on #11251

[chrisvanpatten]

Cross-posting from Slack:

Quick sanity check: I wrote up a quick root-manifest.json generator but I believe it won't actually be viable as part of a build process without some kind of table of contents file (in JSON or YAML or something) describing the order of the manifest, as it seems like the order needs to be intentional. Is that about right?

Not a waste of time because it's still going to dramatically simplify my work on the PR (I'll rearrange the JSON manually, but won't have to write it manually) but I just want to make sure that's a safe assumption.

[chrisvanpatten]

Hey @0aveRyan anything I can do to help you? Do you want me to take back over?

[chrisvanpatten]

Okay this is painfully close to being ready! Just need to get the manifest updated and we're good to go.

[chrisvanpatten]

Okay I would love many sanity checks on this but I believe this is in a good place now.

As part of the re-org, I added a new file, toc.json, which acts as an easier table of contents structure. This makes it possible to auto-generate a root-manifest.json (which is very tedious to write manually, especially when the changeset is as large as this).

Note: I included a docs/generate.php file which generates the manifest from toc.json. I don't think this should get merged into Gutenberg without being rewritten as a wp-cli function or as a node script. (I'd love to do myself, that but I've got a backlog of client work waiting for commits and know we're pushing the timeline limits for 5.0 docs too. Anyone want to hire me so I can work on this full time? 😉) I'll remove the file from the repo before merge, so it will disappear in the squash merge.

(This will be followed up by new documentation—especially user documentation—that I've been working on.)

[youknowriad]

We already have a script to generate docs in docs/tool I think we should consolidate. Having two tools to generate the same documentation is weird.

Also about the new toc.json file. I'm fine with the new file but this makes the root-manifest.json file useless as it's generated and then used to generate manifest.json. We should just generate manifest.json directly.

[chrisvanpatten]

I agree - I plan to remove my PHP script before this is merged. I am time constrained right now so I decided to write it in a language that I was a little more familiar to me so I could get it done faster :)

[mcsf]

Managing relative links in this base is definitely one of the biggest challenges for docs. I can't confidently review them all, but as you've noticed there's quite a few that may be broken.

That said, if you're overall confident that we can iterate on that, I can 👍 this PR!

[chrisvanpatten]

@mcsf I would love to figure out some kind of system that would remove the need to use relative links. If anyone out there has any clever ideas I'm all ears!

[chrisvanpatten]

🎉