There was actually a thread on /r/haskell a few months ago [0] in response to an HN comment. In that thread, a few libraries were mentioned as examples of having amazing docs.
For instance, Gabriel Gonzalez writes a Tutorial module for his libraries, which introduces the basics of the library and shows you the big picture. The tutorial walks you through different pieces of the library, how to use them, and how they come together.
It's hands down one of the most effective ways of documenting I've ever seen and I'd love to see other communities' take on it.
To point out a specific example, you should check out Turtle's tutorial [1].
[0]: https://www.reddit.com/r/haskell/comments/5khts3/on_haskell_...
[1]: https://hackage.haskell.org/package/turtle-1.3.3/docs/Turtle...
It feels like the real issue is that anyone who considers themselves a writer, as well as a programmer, tends to have a blog; and that people who have blogs are incentivized to write "soft docs" as tutorial blog posts for their blogs, instead of as encyclopedia-style or cookbook-style additions to the given library's docs.
I wonder if a programming language could adopt a Code of Conduct discouraging tutorial blog-posts in favor of soft-doc PRs...
There's only so much you can put in docs, and docs can only really encompass one way of learning things.
Blog posts help teach things in other ways, and having that diversity of approaches is great.
This is why, for example, I love Julia Evans' (http://jvns.ca/) work. Most of the blog posts don't really uncover undocumented stuff. They just explore the topic in a novel way, which some people may find more accessible.
Rust is open to importing blog posts into the docs; this has happened a few times (once to one of my own posts!). So I'm happy that there are blog posts out there.
That said, if you're writing a blog post, it's good to see if there are bits than can be put into the docs too.
Instead, they should work to change the incentives -- likely by paying more attention to them as an organization, talking about people who contribute them on the project's page and blog the same as they do for major technical work, and possibly even bringing on maintainers focused on (soft) docs.
Trading attention and prestige for content might work, shaming the people who produce content for not giving you the credit for free is unlikely to.
I don't think projects give soft docs the credit they deserve, so why are people so surprised that people develop that content elsewhere, where they're recognized for it?
I'll only start doing the tutorial doc and/or blog post if others have interest in the library. There's just not enough time :/
I don't think there's a dearth of people willing to write blog posts. There's just a dearth of people willing to do the equivalent job to what Wikipedia editors do for general-purpose articles: collating those "primary sources" into a single, coherent, up-to-date overview.
See for instance the "image" crate docs: https://docs.rs/image/0.13.0/image/
A simple API doc, I don't know where to start. But then if I go to the repo I find a nice intro with some example code: https://github.com/PistonDevelopers/image/blob/master/README...
A post was recently on the frontpage of HN about using Haskell in production [1] that divided the common documentation experience between "hard" and "soft" docs. Far too often with Haskell you only get the 'hard' docs where you get descriptions of functionality and functions but it lacks why (and cohesively how) you would want to use the various functionality.
This makes a strong assumption you are already deeply familiar with the usecase and implementation concept.
This may apply to Rust as well. Rust will likely attract experienced developers, much like Haskell, where in most cases a decent level of code quality would be anticipated. But one of the hardest things to get right as an OSS developer is documentation. You're often so busy with the burden of maintenance that the explanatory side gets sidelined. Especially as a library and the underlying language evolves. So I hope this is a priority focus during their reviews.
[1] https://news.ycombinator.com/item?id=14266462