Web devs, what do you look for before installing open source code?
August 6, 2014 5:34 AM Subscribe
I've been working on an open source project hosted on github. The code (js+react) is just about ready for a big public launch, but I'd like to make sure people have as few reasons as possible to dismiss it. What are your pain points when it comes to external libraries and frameworks? Lack of a clear tutorial? Missing or ugly API docs? What makes you likely to hit the back button?
Things I look for:
1. Recent commits. Obviously that won't be an issue for launch.
2. Creator's other projects. If this is it, I'm a little suspect.
3. A solid README. Description of why you made it, how to install it, and how to use it.
4. Example projects. The more the better. If they are in a separate repo, even better. Really well through out examples go a long way with me.
posted by AaRdVarK at 5:59 AM on August 6, 2014 [2 favorites]
1. Recent commits. Obviously that won't be an issue for launch.
2. Creator's other projects. If this is it, I'm a little suspect.
3. A solid README. Description of why you made it, how to install it, and how to use it.
4. Example projects. The more the better. If they are in a separate repo, even better. Really well through out examples go a long way with me.
posted by AaRdVarK at 5:59 AM on August 6, 2014 [2 favorites]
Oh, what should also be in the README is links to similar, competing projects. Ideally in the "Why you made it?", you'd address why the other available solutions are inadequate for your needs.
posted by AaRdVarK at 6:00 AM on August 6, 2014 [2 favorites]
posted by AaRdVarK at 6:00 AM on August 6, 2014 [2 favorites]
For front-end stuff I find a demo that closely matches my use-case, then work backwards to the library it was built on. (Not a front-end dev).
posted by Leon at 6:03 AM on August 6, 2014
posted by Leon at 6:03 AM on August 6, 2014
What I look for is a very clear, simple example in the first page of README. For a utility library this would be 5–10 lines of code using the library to show what it does. For a web page framework it'd be a simple complete example showing the framework doing something challenging in a clear way.
Beyond that I look for a project that looks alive, and with clear motivations on why this thing is vital open source and not just some abandonware thrown over the wall.
posted by Nelson at 7:47 AM on August 6, 2014 [1 favorite]
Beyond that I look for a project that looks alive, and with clear motivations on why this thing is vital open source and not just some abandonware thrown over the wall.
posted by Nelson at 7:47 AM on August 6, 2014 [1 favorite]
3. A solid README. Description of why you made it, how to install it, and how to use it.
This, along with a small example project of your library in use. One simple enough to follow without going deeply into your documentation but complete enough to show how things are supposed to work.
posted by antiwiggle at 9:00 AM on August 6, 2014 [1 favorite]
This, along with a small example project of your library in use. One simple enough to follow without going deeply into your documentation but complete enough to show how things are supposed to work.
posted by antiwiggle at 9:00 AM on August 6, 2014 [1 favorite]
I like samples showing how to use the thing, or how to swap it in for similar software.
posted by wenestvedt at 9:14 AM on August 6, 2014
posted by wenestvedt at 9:14 AM on August 6, 2014
Nthing looking for signs that the project is being actively maintained, ideally by more than one person. Specifically, bugs are getting fixed, security holes are getting patched, and new features are being planned out and implemented.
Nthing clear, concise documentation that will get me up and running with core functionality as painlessly as possible. I like to see basic examples of usage. Additional, separate code examples are also useful. Tutorials are great, but good core documentation is required.
I'll also look at what my avenues for support are, whether it's developers helping users or users helping each other (or both). I need to know going in that I can reach out somewhere for support if I need it.
Once you get things up and running and have a working demo, promote it. User groups, meetups, workshops, conferences, etc are examples of effective places to do this. It makes a difference when I can see an example of the code in use and have an opportunity to ask questions. There have been a number of frameworks and libraries that I did not give a second thought to (or did not know existed) until I saw them in action this way.
posted by jazzbaby at 9:47 AM on August 6, 2014 [1 favorite]
Nthing clear, concise documentation that will get me up and running with core functionality as painlessly as possible. I like to see basic examples of usage. Additional, separate code examples are also useful. Tutorials are great, but good core documentation is required.
I'll also look at what my avenues for support are, whether it's developers helping users or users helping each other (or both). I need to know going in that I can reach out somewhere for support if I need it.
Once you get things up and running and have a working demo, promote it. User groups, meetups, workshops, conferences, etc are examples of effective places to do this. It makes a difference when I can see an example of the code in use and have an opportunity to ask questions. There have been a number of frameworks and libraries that I did not give a second thought to (or did not know existed) until I saw them in action this way.
posted by jazzbaby at 9:47 AM on August 6, 2014 [1 favorite]
A clear licence - one of the standard Open Source ones, included as a LICENSE.txt in the root of the repo, and also referenced in the Readme.
posted by siskin at 1:45 PM on August 6, 2014 [1 favorite]
posted by siskin at 1:45 PM on August 6, 2014 [1 favorite]
My first question with anything like this is "why do I want it?" - what does it do, and why was there a need for it to be written (what did existing solutions to the same problem not do)? Following that, I'll nth good, clear, well-organised API docs, including code examples, please; don't make me read the code itself in order to figure out how to use it.
For front-end stuff, I also look for an upfront indication of browser support; if this is something I'm planning to use for work, I need to know right off the bat whether our IE8 users are going to be left out in the cold.
posted by ManyLeggedCreature at 12:55 AM on August 8, 2014 [1 favorite]
For front-end stuff, I also look for an upfront indication of browser support; if this is something I'm planning to use for work, I need to know right off the bat whether our IE8 users are going to be left out in the cold.
posted by ManyLeggedCreature at 12:55 AM on August 8, 2014 [1 favorite]
This thread is closed to new comments.
Once I have discovered the packages I tend to pick the one that looks the most active. When was the last update, how many open defects are there, are pull requests being merged, etc?
After that I check out documentation, etc. Good documentation is nice, but if I have the source code not my first concern.
posted by phil at 5:55 AM on August 6, 2014