Personally the thing I find most useful - and that is hardest to write - is a complete and realistic example of an entire flow.
For example on a recent API that I documented this needed to include a complicated OAuth flow (involving Swedish BankID), creation of several orders, and only then listing the actual account details.
Ideally you'll have this as an explicit test case and hike appropriate excerpts directly into your documentation, ensuring that your example actually works even if the API changes! There's nothing more frustrating than minutely explicit demonstration code that doesn't reflect reality - and it's very common!
For example on a recent API that I documented this needed to include a complicated OAuth flow (involving Swedish BankID), creation of several orders, and only then listing the actual account details.
Ideally you'll have this as an explicit test case and hike appropriate excerpts directly into your documentation, ensuring that your example actually works even if the API changes! There's nothing more frustrating than minutely explicit demonstration code that doesn't reflect reality - and it's very common!
Edit: I love the way that Rust's documentation generator allows you to include code snippets that will cause the documentation generation to fail if the code doesn't work! https://doc.rust-lang.org/rustdoc/write-documentation/docume...