New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorganise documentation #11817

Merged
merged 22 commits into from Nov 20, 2018

Conversation

@chrisvanpatten
Contributor

chrisvanpatten commented Nov 13, 2018

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

  • Designer/Developer Handbook (#11251)
  • 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

This comment has been minimized.

Contributor

chrisvanpatten commented Nov 13, 2018

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

This comment has been minimized.

Contributor

chrisvanpatten commented Nov 14, 2018

Todo:

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

This comment has been minimized.

Contributor

chrisvanpatten commented Nov 14, 2018

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

This comment has been minimized.

Member

0aveRyan commented Nov 14, 2018

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

@chrisvanpatten

This comment has been minimized.

Contributor

chrisvanpatten commented Nov 14, 2018

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

This comment has been minimized.

Contributor

chrisvanpatten commented Nov 15, 2018

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

@chrisvanpatten chrisvanpatten force-pushed the big/reorganise-docs branch from 29cc878 to 933221b Nov 19, 2018

@chrisvanpatten

This comment has been minimized.

Contributor

chrisvanpatten commented Nov 19, 2018

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

@chrisvanpatten chrisvanpatten force-pushed the big/reorganise-docs branch from 285862f to b589430 Nov 19, 2018

@chrisvanpatten chrisvanpatten requested review from mtias and WordPress/gutenberg-core Nov 20, 2018

@chrisvanpatten chrisvanpatten changed the title from [WIP] [DO NOT MERGE] Reorganise documentation to Reorganise documentation Nov 20, 2018

@chrisvanpatten

This comment has been minimized.

Contributor

chrisvanpatten commented Nov 20, 2018

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.)

@@ -0,0 +1,131 @@
<?php

This comment has been minimized.

@youknowriad

youknowriad Nov 20, 2018

Contributor

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.

This comment has been minimized.

@chrisvanpatten

chrisvanpatten Nov 20, 2018

Contributor

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 :)

chrisvanpatten and others added some commits Nov 20, 2018

Update docs/tool/manifest.js
Co-Authored-By: chrisvanpatten <hello@chrisvanpatten.com>
Show resolved Hide resolved docs/contributors/reference.md Outdated
@mcsf

This comment has been minimized.

Contributor

mcsf commented Nov 20, 2018

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!

@mcsf

mcsf approved these changes Nov 20, 2018

@chrisvanpatten

This comment has been minimized.

Contributor

chrisvanpatten commented Nov 20, 2018

@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 added some commits Nov 20, 2018

@youknowriad youknowriad merged commit c77cf74 into master Nov 20, 2018

1 check was pending

continuous-integration/travis-ci/pr The Travis CI build is in progress
Details

@youknowriad youknowriad deleted the big/reorganise-docs branch Nov 20, 2018

@chrisvanpatten

This comment has been minimized.

Contributor

chrisvanpatten commented Nov 20, 2018

🎉

grey-rsi pushed a commit to OnTheGoSystems/gutenberg that referenced this pull request Nov 22, 2018

Reorganise documentation (WordPress#11817)
* Initial reworking; props @0aveRyan

* Fixes for the manifest/generators

* A few missed items and small formatting tweaks

* Simplify/flatten the directory structure

* Cheat my way around a merge conflict pt1

* fight the git powers

* JSON version of TOC instead of YML

* Ensure all files have good titles

* Add a generator script and re-generate the root-manifest

* Update docs/designers-developers/designers/block-design.md

Co-Authored-By: chrisvanpatten <hello@chrisvanpatten.com>

* Update docs/designers-developers/key-concepts.md

Co-Authored-By: chrisvanpatten <hello@chrisvanpatten.com>

* Get a handful of internal link references fixed

* Another batch of internal links

* Update docs/tool/manifest.js

Co-Authored-By: chrisvanpatten <hello@chrisvanpatten.com>

* Additional broken internal link fixes

* A few more links

* Revert use of lt/gt symbols in link

* Fix more broken internal links

* Remove docs generator

* Broken manifest.json

ntwb added a commit that referenced this pull request Dec 4, 2018

Restore missing handbook pages after #12411 (#12452)
## Description
Following on from #12411 and #11817 it was noticed that some pages were skipped, as they weren't included in the `toc.json` file previously.

This PR includes several specific fixes which are all interconnected:
1. Adds the Internationalization page along with the Block Tutorial to the handbook hierarchy
1. An additional landing page for the Tutorials index was added
1. `Components` was added to the developers handbook alongside `Packages` and `Data Package Reference` pages.
1. In order to handle the above move, the duplicative declarations of `Packages`, `Data Package Reference` and `Components` were removed from `docs/tool/manifest.js` to prevent them adding as top-level-items. (Are these intended to be top-level-handbook-pages or deep within the developers handbook as the TOC seems to suggest?)

I also took the opportunity to convert `generate.php` from the previous PR into a JS command that allows for `docs/root-manifest.json` to be removed entirely and dynamically generated from `docs/toc.json` so it only needs updating in a single location.  That's the `getRootManifest()` and `generateRootManifestFromTOCItems()` functions which are rather messy, but work (I'm sure someone else could clean that up significantly).

## How has this been tested?
The only testing done so far is the manual review of the final `docs/manifest.json`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment