Recipe-Oriented Documentation

If I’m looking for a library to use in a project, I typically have some use cases in mind. Typically, a library would have been authored to solve a particular set of use cases. So it tends to follow that a library is a good fit if:

1. The use cases align to a strong enough degree

2. The library solves the problem well.

Documentation in software projects tends to follow one or more of the following patterns:

1. API-oriented. Typically generated automatically from the codebase and docstrings. This is useful when you’re already a user of the library, and you want to learn all its capabilities. Very small libraries with very limited and specific functionality can get away providing little more than this.

2. Tutorial-oriented. This might mean an overall “getting started” tutorial, along with documentation about individual components that follows a loose tutorial structure. This works well for frameworks, Django is a great example of this.

3. Recipe-oriented. The focus tends to be around mini use cases, where you want to achieve a certain outcome, and you’re shown how you’d achieve it using the library (and possibly other libraries within an ecosystem). Projects under the Rackt umbrella such as Redux and React-Router do a relatively good job of this, though the examples are simple ones.

As should be obvious by the now, i’m interested in seeing more examples of recipe-oriented (or use-case-oriented?) documentation in open source libraries. In the current climate of extreme library churn in the JavaScript community, it’s incredibly important to be able to quickly evaluate libraries as to their suitability. A common (it seems like it’s daily) occurrence for me is to see a new library, look at the single example and think “that looks interesting”, then file it to one side. It feels like i’m lacking the picture of what use cases they solve. Presumably every time someone asks for a feature in a library, or creates one for themselves, they’re trying to solve a problem. It would be good to see these use cases finding their way into the documentation at the same time as the functionality in the form of recipes.

Other recipes might be developed without any new functionality, but be interesting (or useful) enough to justify being documented. They need not even be fully included in the project’s documentation itself, a link to a relevant stackoverflow answer might suffice.

So essentially, i’m looking for documentation that helps me evaluate the suitability of something, by looking at real examples of how it might be used. Learning how to use something is currently a much smaller problem than deciding whether to use something.