[derefr]

I've seen this problem in the Elixir library ecosystem as well. Regardless of the package, people do see the value in contributing to the commons with PRs for "hard docs" (because they themselves will probably need to read them again later, and don't want to get tripped up again by reading false docs.) But nobody wants to contribute "soft docs" to anything but the language core.

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...

[Manishearth]

I don't think blog posts lack merit.

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.

[SomeStupidPoint]

A CoC that against economic incentives is unlikely to work out.

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?

[sotojuan]

Soft docs are harder and take longer, and as said elsewhere are not appreciated enough. If I'm writing an Elixir library for (what I think) my own use, I'll stop at typespecs, docstring with an example, and a short description.

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 :/

[derefr]

The thing is, it's not that there aren't a lot of blog posts. There are! There's usually at least one blog post about any library I care to use. But it's only a blog post—it's something someone wrote at some point—and so it's not corrected for misapprehensions the author (who is usually not the author of the library) had about the idiomatic way to use the library, nor is it kept up to date with changes in the library like soft docs would be.

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.