Errors

[penelopeysm]

One element of docs I've seen that is very helpful goes something like this:

When you get an error with a library, often the best way to figure out what went wrong is to copy paste the error message into Google and pray that somebody else has run into the same problem before. (obligatory https://xkcd.com/979/)

The most helpful libraries tend to have error codes which link to specific docs pages that tell you (1) why these errors happened; (2) an MWE that triggers the same error; (3) how to fix the MWE; (4) possible further reading e.g. related github issues.

Not only is this a top tier user experience, it means that as a developer you don't have to worry about cramming a lot of explanation into a string in the source code / how to cut error messages down so that it's short without making it useless in the process.

See e.g. the Rust compiler https://doc.rust-lang.org/error_codes/error-index.html for a stellar example of this

There is a similar effort going on with the Haskell compiler https://errors.haskell.org/