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:
- The use cases align to a strong enough degree
- The library solves the problem well.
Documentation in software projects tends to follow one or more of the following patterns:
- 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.
- 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.
- 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.
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.