
How to Spread The Word About Your Code - rnyman
https://hacks.mozilla.org/2013/05/how-to-spread-the-word-about-your-code/
======
smacktoward
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.

~~~
bnferguson
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. :)

~~~
smacktoward
Hmm, interesting. I'm not a C++ jockey myself so I will cheerfully admit the
significance of the "creative coding" term flew right over my head.

------
niggler
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...](http://blog.nig.gl/post/48848761220/just-saying-something-is-gpl-mit-
apache-doesnt))

(always a good read: [http://www.codinghorror.com/blog/2007/04/pick-a-license-
any-...](http://www.codinghorror.com/blog/2007/04/pick-a-license-any-
license.html))

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

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

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

~~~
wyuenho
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/>

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

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

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

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

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

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

------
nate
I've started sticking testimonials in my Readme's.
<https://github.com/n8/multi_fetch_fragments> and
<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.

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

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

