[Lewisham]

I'm surprised people can use Iron at all. I tried really really hard to use it and found the complete lack of documentation (or, worse, outdated blog posts) made it impossible. Is there some magic necronomicon I'm missing?

I had better luck with nickel.rs because it has an examples/ folder with quick recipes of most things you'd want to do.

[PascalW]

My experience exactly. Nickel.rs has a fairly good set of clear examples on its website and then some more on Github.

Unfortunately it seems to be a common trend that Rust projects only provide API docs. While that can be useful I find more 'high level' docs much more helpful especially when you're new to the language and/or framework.

[steveklabnik]

We are in the early stages of having an official docs team; one of the things we want to do is figure out how to encourage better ecosystem docs. Towards that end, right now is the first "doc days": https://facility9.com/2016/06/announcing-rust-doc-days/ we'll be focusing on the rust-lang-nursery crates this time, but will focus on the ecosystem ones in the future!

EDIT: Oh, and I've wanted a good way for Cargo to produce additional, non-API docs through a top-level "docs" directory, but haven't found the time to properly implement it yet :/

[PascalW]

Better tooling will definitely help but I think it will mainly come to focus and priority.

Some packages like Serde for example do provide higher level docs located with the API docs which can work fine.