Developer documentation for @angular-devkit/schematics is misleading and incomplete

[djencks]

🐞 Bug report

Command (mark with an x)

- [ ] new
- [ ] build
- [ ] serve
- [ ] test
- [ ] e2e
- [ ] generate
- [ ] add
- [ ] update
- [ ] lint
- [ ] xi18n
- [ ] run
- [ ] config
- [ ] help
- [ ] version
- [ ] doc

schematics

Is this a regression?

Yes, the previous version in which this bug was not present was: ....

unknown

Description

A clear and concise description of the problem...

The angular-devkit CONTRIBUTING.md file, explaining how to build and locally install angular-devkit, points to the angular-cli README.md, https://github.com/angular/angular-cli/blob/master/packages/angular/cli/README.md#development-hints-for-working-on-angular-cli
However, these instructions only include npm linking instructions for angular-cli, not any of angular-devkit. These instructions do not result in a locally installed schematics command, for instance.

🔬 Minimal Reproduction

Following the instructions at https://github.com/angular/angular-cli/blob/master/packages/angular/cli/README.md#development-hints-for-working-on-angular-cli

git clone https://github.com/angular/angular-cli.git
yarn
npm run build
cd dist/@angular/cli
npm link

does not result in the schematics command calling the locally built angular-devkit/schematics-cli or use of the locally built angular-devkit/schematics

🔥 Exception or Error

🌍 Your Environment

Anything else relevant?

[djencks]

The modified instructions in #15781 work for me to get a local schematics change to work, but I hope there is a simpler way.

[djencks]

I'd prefer that this issue, complete lack of usable instructions for how to build and test the schematics engine/framework, not be conflated with the idea of improving documentation of how to use the existing schematics engine. For instance, most or all of the examples of schematics I found by googling use and explain chain, the solution for passing a Tree & Rules between schematics #15739, whereas I couldn't find any information at all about how to develop e.g. bug fixes.