Minor nit: I agree 110% with the article's point about the need to "Prominently feature a '[noun] is' paragraph", but the example they give isn't that great:
"An excellent example of this in action is on libcinder.org where it states right up front: 'Cinder is a community-developed, free and open source library for professional-quality creative coding in C++.' Perfect!"
I'd push back on the assertion that this is perfect. "Library for professional-quality creative coding in C++" is actually a pretty fuzzy, non-descriptive way to describe your project. The only real thing you've learned after reading it is that it's for C++; you don't know anything specific about what it does, just that it's "professional" and "creative."
The Cinder developers actually have a much better one-sentence description at the top of their About page (http://libcinder.org/about/):
"Cinder provides a powerful, intuitive toolbox for programming graphics, audio, video, networking, image processing and computational geometry."
There's still some fluffy words in there ("powerful," "intuitive"), but overall it gives you a much better answer to the question "What is this?" than the tagline cited in the article does.
This is a very fair nit to pick! I think the bold presentation of the definition on their homepage (not a particularly common thing to see, alas) may have caused me to give it more favor than it deserves. It's not bad but the other one is certainly better.
In the case of Cinder "creative coding" is in reference to a very specific thing and using that term tells me exactly what sort of library it is. Namely being familiar with other "Creative Coding" frameworks such as OpenFrameworks, Processing, etc I generally know what Cinder is offering and how it's going to approach the problems. The about page description doesn't tell me its approach, just its content and approach is very, very important in these (they almost always follow the same structure).
That said, using the "Creative Coding" term makes it all very inside baseball and I totally agree it could be better. openFrameworks falls into the same trap with: "openFrameworks is an open source C++ toolkit for creative coding." Signaling to those who know without telling those who don't.
I do feel like Processing does much better with "Processing is an open source programming language and environment for people who want to create images, animations, and interactions" even if it isn't prominent. Then again Processing is the one that pretty much coined this whole "Creative Coding" thing. :)
It's just as well the first sentence was followed by a link to the second. As someone who didn't recognise the term "Creative Coding", I was just one click away from understanding.
My understanding is that "creative coding" is actually a fairly well-specified term for those "in the know". I had almost exactly the same question and someone straightened me out. I'll try to find the thread.
I wish licensing was emphasized more in this discussion.
Including a license is the #1 reason myself and many other people stray away from code on the internet. I won't touch a project if it's not stated properly.
And to be clear, just writing that your project is MIT licensed or sticking it in a package.json or making a small remark in your README doesn't cut it. You need to follow the terms of the license you wish to use (my comment on the matter: http://blog.nig.gl/post/48848761220/just-saying-something-is...)
I'm curious - have you been burned by issues with licenses in the past? I've never had licensing affect me in any tangible way and so they are really more of a vague theoretical, and thus low priority, concern for me. But I am vaguely aware that this is theoretically the wrong position to have while yours is the right one.
> I'm curious - have you been burned by issues with licenses in the past?
If you count "not being allowed to use $LIBRARY because your company's lawyers won't let you use improperly code", then this is incredibly common.
The alternative scenario - using code released under an ambiguous license and then later getting sued for it - is much less common with large companies simply because good legal teams won't let that happen (see the above scenario).
I'm sure there have been examples of it, though - I know I've heard of those stories myself, even; I just can't think of them at the moment.
It's better to be safe than sorry, as the saying goes. I've never been burned personally. I'm also pretty sure that anyone working for a large software company is warned about using third party code or snippets found on expertsexchange or stackoverflow or random blogs.
Normally people are well intentioned, but sometimes you stumble upon repos with very strange licenses (for example, a javascript repo that has operating system restrictions https://github.com/stephen-hardy/xlsx.js/issues/8 ).
It's usually not of a concern for most people working on small projects (after all, another party has to notice and then decide to take action), but if you are trying to enter an industry with a highly litigious incumbent then you should make sure your ducks are in a row first.
That all makes perfect sense. I think I misread your original comment somewhat - I read it as "licenses are the #1 thing I consider when evaluating projects", rather than "of the projects I decide not to use after evaluating, licenses are the #1 reason for that decision", which isn't the same thing at all.
When my company was getting aquired we sent them the license details of some 50 projects as part of the DD, the lawyers emailed back and said to only include licenses to things we that were either not open source or that were substantial to the tech stack. SciPy, NumPy, Python, and GNU/Linux was all that was sent.
That codinghorror.com article is great and is a must read for any developers on the fence about attaching a license to their open source projects. I have to admit I was feeling both awkward and douchey debating whether I should attach a license to a few miscellaneous projects that no one may ever even see.
"That's ironic, considering the whole reason I posted the code in the first place was so other developers could benefit from that code. I could have easily avoided this unfortunate situation if I had done the right thing and included a software license with my code."
You're completely off on this subject. The copyright holder can do whatever he wants with it - including releasing it under multiple, different licenses. The onus is on the licensee - a person who obtains the licensed code, to honor the license given to him. It's the responsibility of the licensee to comply with the terms of the license and republish whatever needs republishing when (if) he redistributes the code.
None of your statements contradicts points from my comment, my post, or the coding horror post. If you are releasing code and not putting in a license or doing so improperly, don't expect others to use it. CH focused on one facet (missing a license) while I focused on a different facet (how to add a license properly)
> And to be clear, just writing that your project is MIT licensed or sticking it in a package.json or making a small remark in your README doesn't cut it.
My point is that it does cut it. It's up to the licensee to include the license, not the copyright holder. There is nothing improper about specifying the license and not including it in its entirety. That's just your personal interpretation of it, that has nothing to do with copyright law.
While a lot of this may seem obvious to people who have promoted multiple projects, I think having all of the advice laid out in a simple guide is very helpful. I recently released my first open source side project [1], and realized I didn't really know what to do to promote it beyond trying to get some exposure on HN (which failed). I'm going to try some of this advice this week, starting with picking a better name!
Agreed, and also failed to promote my project a few times on HN. In January I've decided to take a different route and promote on /r/javascript instead and all of a sudden it got bumped to number 1. Got picked up by tbranyen and eventually jashkenas.
Oh, BTW, my Backbone-based grid clocks in only 6.2K minified and gzipped :) Much better documentation too. No column resizing and reordering at the moment, but working on it for the next version :P
That's good advice. I'll probably give Reddit a shot at some point.
I am pretty jealous of your API docs for backgrid. What do you use to generate that? Also, my 17kb quote is minifed but not gzipped. ATable comes out to 5.1kb gzipped. That being said, 6.2kb is pretty damn impressive considering some of the extra functionality that backgrid has.
Ah thanks for clarifying. I couldn't find a minified version of aTable on your Github repo so I couldn't double check.
A number of people have asked me what I used to generate the documentation. The truth is I didn't use any. I just hand-coded the whole HTML doc in Emacs using zencoding-mode. Styled it with bootstrap. The header serif font is a Mac font called Hoefler Text. The code editor is codemirror. That's it. The reason I do this is because I find pretty much all the documentation generators out there very lacking in layout controls. I could use Sphinx but I'll have to end up customizing the hell out of the default themes anyway. Might as well do it the basic way.
Totally agree about the existing doc generators.
Btw- I didn't start creating aTable because of a perceived shortcoming of Backgrid. If Backgrid existed a month or so earlier, I probably would have just tried to contibute. By the time I knew about Backgrid, though, I already had a mostly-working codebase and didn't want to throw it away.
Great article - it's a great thing that now people need to compete to give out their work for free.
One thing might be missing in Step 1 (get ready your project) is that show your dedication to the future of the project. That's a very important factor for me considering use or getting involved with an open source project.
> A benefit of having a relatively unique or uncommon name is so you can search for it over time (or even set up a Google Alerts notification for the name) and find mentions of your project without many irrelevant results popping up.
A million times this. It's so impossible to search for anything related to LESS. I wind up searching for "less" "css" "remaining part of query" but it still brings up a lot of irrelevant stuff.
Well yeah, except for the Google Alerts bit - Google Alerts seem to be all-but-dead these days. mention.net is a reasonable alternative - with a limited free offering and paid plans for more detailed/serious use.
Curious. I did some searching and it does seem many are having issues with Google Alerts. I continue to receive mine each day and they still come in useful. Odd.
Having a popular open source project is mostly a matter of luck. Most people that use Node don't use it because don't use Node because it's a brilliant platform. People mostly use Node because everyone else uses Node.
Once you're popular, most of the popularity is due to being popular. There's very little a developer can do to make their a "popular".
Can I emphasize the use of code samples right on the homepage?
As an example, Requests (http://docs.python-requests.org/en/latest/). If you've ever done URL fetching in Python you can immediately see the value and cleanliness of it.
A couple of projects I've come across don't have anything like it, and only have more of an API reference. I understand it may be early days and documentation hasn't yet been a priority, but I really love to see the advantages of the library, particularly if you compare it to the old way of doing things.
i've had good success with submitting some of my github'd js projects to http://dailyjs.com, decent amount of exposure there. make sure you have at least a demo/example page up somewhere, too.
"An excellent example of this in action is on libcinder.org where it states right up front: 'Cinder is a community-developed, free and open source library for professional-quality creative coding in C++.' Perfect!"
I'd push back on the assertion that this is perfect. "Library for professional-quality creative coding in C++" is actually a pretty fuzzy, non-descriptive way to describe your project. The only real thing you've learned after reading it is that it's for C++; you don't know anything specific about what it does, just that it's "professional" and "creative."
The Cinder developers actually have a much better one-sentence description at the top of their About page (http://libcinder.org/about/):
"Cinder provides a powerful, intuitive toolbox for programming graphics, audio, video, networking, image processing and computational geometry."
There's still some fluffy words in there ("powerful," "intuitive"), but overall it gives you a much better answer to the question "What is this?" than the tagline cited in the article does.