Suggestions

For @knz

I was looking through the docs trying to find out how to register a migrated error, and it took me a little bit. So I wanted to suggest how to make that more visible, and then I thought while I'm at it, a couple more suggestions:

- [ ] First, the [docs on migrating/renaming an error](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20190318_error_handling.md#handling-error-typepackage-migrations-and-renames) are a little buried and could perhaps be linked in the README. You talk about forward compatibility in the README, which I understand in part to involve [forwarding errors through unaware intermediaries](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20190318_error_handling.md#guarantee-perfect-forwarding-for-unknown-types) but from the name it sounds like error migration is part of it, so I was surprised how much I had to dig to re-find this data.
- [x] `RegisterTypeMigration` could perhaps be part of the "forwarded methods" so it shows up in the main package, looks like I currently need to import `errbase` to get at it.
- [ ] The README could use a sample of the ultra-awesome stack trace format!
- [ ] The compatibility table is a bit intense to be at the top of the README. I remember back when I first came across this package, it was a little confusing—my takeaway was, "wow, this thing has lots of features I guess". I feel like you might be better served by having the top of the README dedicated to a simple bullet-point list of features and some code samples showing what it looks like in practice.
- [x] Could have a godoc badge up at the top of the README: [](https://godoc.org/github.com/cockroachdb/errors)
- [ ] Perhaps rethink how the data on custom errors is provided. The information is pretty dense and unstructured; I would suggest more subheadings for specific tasks like "Custom Leaf", "Custom Wrapper", "Over the Network", or some such. Also perhaps consider putting the writeup in its own document because there's a lot to the subject and it can be overwhelming to someone landing on the main page of the repo.
- [ ] This is subjective, but I think in general the README could express more through code samples:
- [ ] The section on [Available Error Leaves](https://github.com/cockroachdb/errors#available-error-leaves) could show little fake error scenarios, using that applicable function, and then retrieving the data, with additional details in comments.
- [ ] The section [How to Use](https://github.com/cockroachdb/errors#how-to-use) could perhaps be shown in code.
- [x] I question the necessity of [API (not constructing error objects)](https://github.com/cockroachdb/errors#api-not-constructing-error-objects), since Godoc is probably better suited for this anyway.
- [ ] I don't think the `exthttp` package is mentioned as a useful tool, more as an example for when you're building your own error types, but I think it adds value. Also `extgrpc` isn't mentioned, although that one's entirely my fault because I never added docs for the work I did 😉
- [ ] I feel like the project deserves a cool logo! (😄 ) Maybe a variation of the cockroachdb logo?

I'm aware that I'm armchair-quarterbacking and should probably put a PR where my mouth is, but I'm in the middle of other things and just felt compelled to jot down some notes. Interested to hear your thoughts!