6 ms·

How to Spread The Word About Your Code

229 points by rnyman 13y ago

kailuowang 13y ago
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.
jwoah12 13y ago
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! [1]: http://jarwol.com/aTable/ http://jarwol.com/aTable/
- wyuenho 13y ago
  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 http://backgridjs.com/ http://backgridjs.com/
  - jwoah12 13y ago
    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.
    - wyuenho 13y ago
      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. The API docs however is generated using JSDuck.
      - jwoah12 13y ago
        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.
    - bink-lynch 13y ago
      API docs for backgrid are fantastic. Looks like the docs are generated using JSDuck: https://github.com/senchalabs/jsduck https://github.com/senchalabs/jsduck.
smacktoward 13y ago
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/ 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.
- petercooper 13y ago
  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.
- andrewflnr 13y ago
  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. Edit: Ah yes, on an HN post about the very same framework: https://news.ycombinator.com/item?id=3208552 https://news.ycombinator.com/item?id=3208552
- bnferguson 13y ago
  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. :)
freework 13y ago
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".
nate 13y ago
I've started sticking testimonials in my Readme's. https://github.com/n8/multi_fetch_fragments https://github.com/n8/multi_fetch_fragments and https://github.com/n8/cohort_me https://github.com/n8/cohort_me It's hard to split test these if they are working, but these two projects have gotten a lot more visibility than other open source stuff I've put out. Over an over again I see social proof have profound effects on getting people's attention.
niggler 13y ago
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-gpl-mit-apache-doesnt http://blog.nig.gl/post/48848761220/just-saying-something-is...) (always a good read: http://www.codinghorror.com/blog/2007/04/pick-a-license-any-license.html http://www.codinghorror.com/blog/2007/04/pick-a-license-any-...)
- sanderjd 13y ago
  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.
  - niggler 13y ago
    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 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.
    - sanderjd 13y ago
      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.
crazygringo 13y ago
> 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.
- bigiain 13y ago
  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.
  - petercooper 13y ago
    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.
leeoniya 13y ago
i've had good success with submitting some of my github'd js projects to http://dailyjs.com http://dailyjs.com, decent amount of exposure there. make sure you have at least a demo/example page up somewhere, too.
MasterScrat 13y ago
I'm surprised GitHub Pages isn't mentioned in the "official homepage" part. Easiest way by far to make a profesional looking project website. http://pages.github.com/ http://pages.github.com/
dougk16 13y ago
"You spent an entire weekend building a library..." Haha, more like an entire five years and counting! Thank you for the advice though. It sounds reasonable and I will use it all once I'm ready to release my creation upon the world.
decadentcactus 13y ago
Can I emphasize the use of code samples right on the homepage? As an example, Requests (http://docs.python-requests.org/en/latest/ 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.

229 points by rnyman 13y ago

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.

jwoah12 13y ago

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! [1]: http://jarwol.com/aTable/ http://jarwol.com/aTable/

wyuenho 13y ago
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 http://backgridjs.com/ http://backgridjs.com/
- jwoah12 13y ago
  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.
  - wyuenho 13y ago
    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. The API docs however is generated using JSDuck.
    - jwoah12 13y ago
      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.
  - bink-lynch 13y ago
    API docs for backgrid are fantastic. Looks like the docs are generated using JSDuck: https://github.com/senchalabs/jsduck https://github.com/senchalabs/jsduck.

smacktoward 13y ago

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/ 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.

petercooper 13y ago
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.
andrewflnr 13y ago
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. Edit: Ah yes, on an HN post about the very same framework: https://news.ycombinator.com/item?id=3208552 https://news.ycombinator.com/item?id=3208552
bnferguson 13y ago
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. :)

freework 13y ago

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".

nate 13y ago

I've started sticking testimonials in my Readme's. https://github.com/n8/multi_fetch_fragments https://github.com/n8/multi_fetch_fragments and https://github.com/n8/cohort_me https://github.com/n8/cohort_me It's hard to split test these if they are working, but these two projects have gotten a lot more visibility than other open source stuff I've put out. Over an over again I see social proof have profound effects on getting people's attention.

niggler 13y ago

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-gpl-mit-apache-doesnt http://blog.nig.gl/post/48848761220/just-saying-something-is...) (always a good read: http://www.codinghorror.com/blog/2007/04/pick-a-license-any-license.html http://www.codinghorror.com/blog/2007/04/pick-a-license-any-...)

sanderjd 13y ago
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.
- niggler 13y ago
  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 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.
  - sanderjd 13y ago
    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.

crazygringo 13y ago

> 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.

bigiain 13y ago
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.
- petercooper 13y ago
  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.

leeoniya 13y ago

i've had good success with submitting some of my github'd js projects to http://dailyjs.com http://dailyjs.com, decent amount of exposure there. make sure you have at least a demo/example page up somewhere, too.

MasterScrat 13y ago

I'm surprised GitHub Pages isn't mentioned in the "official homepage" part. Easiest way by far to make a profesional looking project website. http://pages.github.com/ http://pages.github.com/

dougk16 13y ago

"You spent an entire weekend building a library..." Haha, more like an entire five years and counting! Thank you for the advice though. It sounds reasonable and I will use it all once I'm ready to release my creation upon the world.

decadentcactus 13y ago

Can I emphasize the use of code samples right on the homepage? As an example, Requests (http://docs.python-requests.org/en/latest/ 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.