Add actual "User Manual"

[schlessera]

Right now, the handbook is mostly a reference, with tips and tutorials sprinkled throughout.

Apart from the "Quickstart" guide, there's no real user manual that explains all the concepts for a new user in a linear progression.

I'd like to plan for a real "User Manual" with a clean list of linear chapters that takes new users by the hand and provides a proper introduction that can be read from start to finish.

[schlessera]

Also, there should be clear sections that separate user-facing content from contributor-facing content.

[schlessera]

A good first step would be to restructure the sidebar so that it matches the structure in the index page:

+-- Guides
|   |
|   +-- Installing
|   +-- Quick start
|   +-- Commands cookbook
|   +-- Common issues and their fixes
|   +-- External resources
|
+-- References
|   |
|   +-- Global parameters
|   +-- Built-in commands
|   +-- Package index
|   +-- Internal API
|   +-- Documentation standards
|   +-- Hosting companies
|   +-- Shell friends
|   +-- Integrated tools
|
+-- Contributing
|   |
|   +-- Bug reports
|   +-- Contributing
|   +-- Governance
|   +-- Implementation details
|   +-- Philosophy
|   +-- Pull requests
|   +-- Release checklist
|   +-- Roadmap
|
+-- Misc
    |
    +-- Plugin unit tests
    +-- Website and Package Index wish list

[schlessera]

@danielbachhuber Do you know whether there's a limit to the indentation level in the WP.org menu structure?

[danielbachhuber]

Do you know whether there's a limit to the indentation level in the WP.org menu structure?

I don't believe so. If we go more than a couple levels deep, we might pass what there's available CSS for (which is easy enough to fix).

[schlessera]

Okay. I think we're only bumping from 1 level deep to 2 levels deep with the above change, so that will hopefully still fit.

[schlessera]

@danielbachhuber I cannot find a source of the actual menu ordering on the handbook site. Is this done through a WordPress menu on the make.wp.org backend?

[danielbachhuber]

Is this done through a WordPress menu on the make.wp.org backend?

It's based on the menu_order attribute of handbook pages.

[danielbachhuber]

I have a couple of thoughts on this:

1. The issue itself doesn't seem very actionable at this point because it has a potentially massive scope. Before we embark on this, we need to identify and estimate a more strict scope.
2. Rather than embarking on refactoring all of our existing documentation at the start, it would be a lower risk activity to create a new documentation site for testing purposes, and then run user tests against the new site to validate the proposed changes.

[stkjj]

Let me try this … https://github.com/wp-cli/handbook/issues/87#issuecomment-314829171