I enjoyed rust's documentation a lot, both when learning the language and when working with it - here's a good example:
[https://doc.rust-lang.org/std/result/enum.Result.html](https://doc.rust-lang.org/std/result/enum.Result.html) * explanations that zoom in and out - both methods, classes and modules are written such that each makes sense on its own but links to the greater picture - modules docs explain the abstract problem that's solved etc. * examples that can be run * a common style across the documentation, with guidelines for authors - helps navigation, quick scanning and anticipating where to find things * the source code is linked, so it's easy to quickly look up the implementation as well * markdown * examples are not part of the code, but rather sit in well-marked sections of the doc comment - runnableExamples are really distracting when positioned next to the implementation - it's very hard to tell where examples end and implementation starts, visually There's also a book that goes over the trickier concepts: [https://doc.rust-lang.org/stable/book](https://doc.rust-lang.org/stable/book)/ Good documentation is also easy to write and allows the code to stay beautiful afterwards - for example, it's hard to document fields because the comment is expected on the same line after the field - there's usually very little room there to write good docs.. Perhaps the hardest thing to satisfy is that good documentation requires active maintenance - if you have that, the rest falls in place..
