Million Dollar Software--A Nickel of Documentation

I'm a fan of open source software.

I run various distributions of Linux on all my computers. I use Libreoffice, Emacs, and Geany for my productivity needs. I enjoy using Dosbox for running old Dos games, Firefox and Google Chrome for surfing the web, Git for version control, and python, perl, awk, sed, and free pascal for programming. And that's just the day-to-day stuff.

Like I said, I'm a fan.

But it's now 2013. And I have to say, enough is enough. The documentation that exists for most open source projects is total crap. Let me say this up front:

We--Your Potential Users--judge your program by its documentation.

When I look back at the list of open source software listed in the first paragraph, one of the commonalities shared between these programs is how well-documented most of them seem compared to the vast majority of open source software, and even then, I often find myself gritting my teeth in frustration and searching the web for more detail.

The simple fact is that open source software will never be judged--by 99% of computer users--on the basis of its technical merit. This isn't because nobody cares. Many of us actually do. No, the reason we don't judge most software on its technical merit is because we can't figure out how to get the damn thing to run long enough to give it a proper test drive.

Don't programmers know this?

Calling All Programmers: You just spent forever programming a masterpiece. It's brilliant. It's open source. It's free. It clones some program that earns millions on the open market. And you're giving it away! You are a very generous person.

But who cares!!! You just wasted your time if nobody can get it to run!!!

Give us documentation. Give us tutorials. GIVE US EXAMPLES!!!

For the love of all that is holy, give us a website that makes it stupid easy to figure out (1) how to download your program and (2) how to run it.

Documentation is the key to success. Like I said before, we judge your program by its documentation.

You just spent months or even years programming something. Spend a weekend to tell us how to use it.