To Whom It May Concern:
I am a fan of Open Source projects. I strongly support all Open Culture, particularly in Libraries, Archives, and Museums (LAMs). However, I must bring something to your attention. All too often, I read announcements of some new open source software that is perfect for “institutions of all sizes”. Your average reader, who is not completely inept with technology — but is not a software engineer — goes to the project site. The installation instructions go something like this:
1. We are not going to tell you which server architecture this works on because you clearly should be smart enough to figure that out.
2. Download this package.
3. Compile the package.
4. Obviously there are 300 dependencies, but we are not going to tell you what they are. Any decent institution would have them installed already.
5. Change system configurations to serve local needs. We’re not going to tell you what that means or how to do it.
6. Use the API from your core system to feed in this data. If your current API doesn’t work, please write one according to the specs on some other project you’ve never heard of. Note that the documentation of that other project hasn’t been updated in eleven years, but you’ll figure it out. What? Your system doesn’t have an API?!?!?! You must be joking. *Everyone* has an API.
7. Earn a PhD in computer science.
8. Change your entire server environment including reinstalling your core systems on some other platform, breaking everything and requiring tens of thousands of dollars in development work to put all the pieces back together again.
9. Type the following commands in the command line. Note that they look like a SHA-256 hash, but they are actually really simple commands that *everyone* should know.
10. Spend nine weeks on Stack Overflow trying to figure out all the parts that we did not explain here.
11. Ask a question on Stack Overflow where the only respondent points you to the documentation online or a W3C standard. 1
12. Voila! It works!
13. Subscribe to updates from the project and receive an email the next morning saying that development on the project is suspended because the entire project is being moved to a different architecture. Realize this means you will get to start over at step one.
Addendum: We didn’t write any documentation. If you need to figure something out, just read the code.
Please, please do not say that this project is meant for “institutions of all sizes”. Please do not advertise it as “easy” or “simple”. Please tell it like it is – it’s raw, it’s meant for experts, and you don’t care if anyone else can get it to work. I appreciate that you are trying to do something good, but your good will is meaningless when it stands against the disappointment of every reader who wanted to try out your project but was completely stonewalled by your “easy” installation instructions.
Just knock it off already.
1. With special thanks to @metageeky for number 11 in the list! ↩