
How To Make Your Open Source Project Really Awesome - Garbage
http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/
======
nate
I've started treating the README's to my open source projects almost like
landing pages for products. So I now do a couple things I might do for a
product page: lead with pain and testimonials.

I'll open with something that describes the pain someone might be going
through to catch their interest with the project. And I'll also make sure to
include a testimonial or two from folks using the project. Here are a couple
examples:

<https://github.com/n8/multi_fetch_fragments>

<https://github.com/n8/cohort_me>

I don't have enough data to scientifically judge the results. But since I've
started doing this I do know my most recent three open source projects have
gotten a lot more traction than previous projects.

~~~
temp1234xd
Concerning the opening quote on your Multi-fetch Fragments project:
<https://www.biglittlepond.com/> currently gives an SSL error. While obviously
completely un-related to you, your project seemingly 'promoting' an website
that can't do SSL certificates properly does have some negative connotations
;).

------
h2s
I agree really strongly with 99% of this. I make a fairly niche command-line
application, and I'm convinced that it would have exactly zero users if I
didn't put as much time into documenting it as I do.

I think the GitHub stats make this point fairly well:

    
    
        Pushed 79 commits to h2s/ppl Apr 14 - Apr 20
        Pushed 34 commits to h2s/ppladdressbook.org Apr 14 - Apr 20
    

That's almost a documentation commit for every other commit to the application
itself. It's a lot of work, but seriously, what's the fucking point otherwise?

I also agree about abandonware. I keep encountering this, and it's pretty
tiresome. Somebody built some well-received little tool a year or five ago,
and for a time they loved it. Now they're bored of it, and they make just
enough of a token effort to sustain the project to temporarily fool you into
using it. I even have a different project of my own that's starting to creep
into this territory. Hopefully I will not make a hypocrite of myself when the
time comes.

The only thing I don't agree with particularly is this.

    
    
        > Make sure the title starts with ANN or [ANN] to
        > indicate that it is an announcement, e.g.
        >    ANN Welle 1.5.0 is released
    

This seems an oddly specific recommendation to be making. We're doing
Hungarian Notation for project blog post titles now?

Anyways, that minor thing aside, I think this is an absolutely excellent
primer for anybody considering starting an open source project. If, while
reading this, you find yourself thinking "How silly, ain't nobody got time fo'
dat", then you're probably starting out your project with quite a low ceiling
on its potential usefulness.

~~~
AndreasFrom
It appears to be a Usenet / mailing list / email abbreviation [1]. I could see
myself appreciating it when skimming mailing lists or large documents, but
then again I could just use Ctrl-f or the like. [1]:
<https://en.wikipedia.org/wiki/Announcement_(computing)>

------
zalew
@ Document Your Project

here's a good talk about it <http://pyvideo.org/video/1795/write-the-docs>

_> bitbucket is a good service, no doubt. But people who choose it for public
code are just being difficult (according to me)_

this argument is a pile of horseshit (according to me).

~~~
hosay123
Actually if you consider open source as proxy for the communication of ideas,
writing docs might be seen as the _primary_ goal of any project.

Without docs expressing what code is supposed to do, a random git repo is just
another worthless, opaque pile of buggy spaghetti to any random bystander.
With docs, said bystander is empowered with the original intent, and might
even extend your idea far beyond what you ever envisioned (aka "the power of
open source").

A side point is that many people (myself included) will look for docs first,
as some measurable proxy of code quality. Shitty docs often means shitty code
or shitty idea.

------
csmatt
This is mostly obvious. I documented the hell out of my Google Voice app for
dumb phones <https://code.google.com/p/gv4me/> , but no one else ever
contributed to it. That's the only project I've built that I've ever had much
luck with people using. I've put together various useful things here
<https://github.com/csmatt> that I haven't had even had 'user traction' with.
I'm starting to think that open source/side projects need the same level of
marketing as commercial products. Am I doing it wrong?

------
andyl
The dependency thing is a big deal. So much wasted time tracking down
dependencies for my Ruby projects...

I recently discovered RVM autolibs. Wow - what a great idea.

Is there a way to make 'autolibs' work with bundler, or rbenv?

------
niggler
"State What License You Use"

I would go further and say "state what licenses apply to code you didn't
write". It's dangerous to see people cull code from the internets without
properly understanding who holds the copyrights.

As explained in coding horror: "Experienced developers won't touch unlicensed
code because they have no legal right to use it."

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

------
derekp7
One thing I've found when documenting any of my projects -- if it is too hard
to explain clearly, then something is probably wrong with the interface. So
what I end up doing is writing a document that makes sense, then I go back and
re-write parts of the app in order to fit the documentation. Then, before
tagging a release and announcing it, get a few other people to look it over
first, just to make sure that everything matches. Oh, and having an automated
test suite that at least checks all common cases and various edge cases will
make sure that you don't have to hurry up and push a .01 followed by a .02,
.03, etc. release.

Now, that being, said, what is the best way to get a good group of pre-release
testers? So far I haven't had too many people bite.

------
erikb
It's exactly like I thought from the title: The author lives with good and bad
documentation every day so he can say clearly the requirements of a good
documentation and what he's missing. The problem is that the topic says "this
is a how to do it better" and that is not done by saying the requirements.

Of course it's hard to say how to do it better, which is exactly the reason
why most people don't do it better: the good people often can't say why they
are doing it better, just that they are doing it better. So what the author
wants to teach here is something the author needs to learn first himself.

I feel a little disappointed for not getting that how to but wish good luck to
the author, because he seems to be on the right path.

------
dllthomas
Does anyone know a good format/toolset for writing docs, wherein I can embed
tests of claims made in the documentation, so that the team (maybe just me,
maybe me and others, maybe just others later) is forced to notice when the
code and docs drift apart?

~~~
jacobian
Sphinx (<http://sphinx-doc.org/>), my tool of choice for writing
documentation, includes an extension that does this: <http://sphinx-
doc.org/ext/doctest.html>.

------
level09
add to this, a demo page (when applicable). I find it very helpful, as people
will have a direct view on the project while seeing it in action, and saves
them the time to clone, compile/run the project and test it.

