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.

Five Rules For Becoming a Novelist

One of my Lifetime Resolutions is to become a published writer. To that end, I've decided to establish the following rules for myself:

5) Write only in LibreOffice in Liberation Sans font--the open source clone of Arial--set up under Styles and Formatting (F11) so that formatting can be set up once and for all and then forgotten. Any other setup just encourages yak shaving. And no LaTeX no matter what.

4) Save only with Version Control. There should never be multiple copies lying about. That only creates confusion.

3) Save everything to offsite backup. Never depend on any single machine or source. It will inevitably get lost or fail.

2) Never write in the first person. I cannot write in first person to save my life. Never again!

1) Write at least 1 page every day and once written, only edit--do not massively change what has been written. No matter what. Sick. Exhausted. Swamped with work. On Vacation. Trapped at the bottom of a well. I don't care. No excuses. You must write to be a writer.

Note: These are just for me. I'm not recommending them for anyone else.