A library is a risk

The problem with the person who dumps their junk on the street is that he is not considering his ‘contribution’ from the perspective of the people who might be looking for such things — or from the perspective of the people who might want to use the street.

People who are looking for old fridges etc. have places that they will go for that — junk yards, freecycle, ebay, etc. And people walking down streets have expectations of what they will find on those streets. Once you take those things into account, you won’t leave your old fridge on the street if you actually care about other people.

Now, people looking for software libraries have a specific task that they need to achieve. They are looking for a library because they believe the task can be abstracted into a library somehow, and they don’t want to have to write the code themselves. They then go to Google or a framework/programming language specific repository with keywords for that task.

Every result they find is an avenue that might need exploring. And everything they find which is not suitable is junk that is just getting in their way. The developer has to do 3 things:

Evaluate whether a certain package could possibly do what they need. Install the package, possibly including some kind of configuration. Write the code to get the package to do what they need.

And then, possibly, the developer may need to patch/fork your code to produce a version that does what they need.

Every step represents increasing commitment in terms of time. At each step, every second that I have to spend to find something out is time that I am spending, and therefore potentially wasting, because of your library. I will not know until I have actually finished the last step whether your library will help me — it could easily have some flaw that makes it useless for me.

So your library represents risk to me, especially as I always have alternatives — another library, or just writing the code myself. At each point, I’ve got to assess whether it is likely I will succeed with this package. I’ve made an investment in this library already, but will it reward continuing investment, or will it turn out to be another dead end? Should I get out now?

So, at the very least I need an overview that tells me what a library does. Without that, every second I spend looking at a library is probably time wasted. It seems ridiculous that someone would publish a library like this, where there is simply nothing to help you know how you are supposed to use it, but many instances exist (I picked that one at random), and, thinking that you must be missing something obvious, you actually spend time searching for any docs, before concluding that there is no documentation whatsoever, not even a single source code comment that might give you a clue.

I hate your package already, and wish it didn’t exist, just like the fridge on the street. You have probably not helped anyone, and you have certainly hindered me.

But I need to know more than what is covered by the overview, since it is very unlikely that the default, simple case will cover all my needs. I also need to know what customisation or extension points there are. If none are documented, I can only presume that none exist.

Even if they do exist, I cannot know from reading the source whether they are essentially accidental or not, and this leads to another point: