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.

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

As an aside, how does this cooperate with cache_digests from rails 4?

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.

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)

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

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.

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

Which part? Do you think bitbucket is not a good service or that bitbucket has reached a critical mass for open source hosting or that github hasn't reached a critical mass?

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?

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?

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

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.

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.

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?

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.

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.