Comment by dmix | Hacker News Reader

Comment by dmix | Hacker News Reader

This is something Haskell could really benefit from. Largely just through writing documentation for common libraries.

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

Agreed. I feel like the state of documentation of Haskell libraries in general could be much better.

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

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

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?

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

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.

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.

Yes, this is very true of most rust docs that I've seen as well. Lots of libraries have the auto generated docs describing the functions and types usually at a per-module level but fewer have anything higher-level

Yes, and that's definitely something we hope to address with the Blitz, both by beefing up top-level library docs, and through the Cookbook.

Most of the time I find that the lib's github's README.md contains the introduction and overview that I want to understand how the library works. Unfortunately it's not in the docs themselves, but I hear that the Rust team is working on improving that.

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

Reply on news.ycombinator.com