Watching this ongoing debate about poor documentation in Linux and I now feel forced to express my feelings, this should be listed as the number one bug in Ubuntu, not Windows as it is currently. But not from the same angle that I see it taken from in the current blogosphere.

How hard is it to use Pigeon Really?

How hard is it to use Pigeon without consulting some 500 page manual, its just not necessary for the greater part when using GUI applications. OK agreed, the man pages seriously need some help. They really need to start adding examples to the entries. Have you ever tried to un tar an entire directory only to find that tar xzf *gz doesn’t work and don’t know why. Off to Google we go and usually with these sorts of queries, we would probably be safe. But this isn’t the million dollar issue and the one that is majorly hampering Linux and the greater creation and adoption of quality open source.
The big issue is the documentation surrounding development. Essentially if you want to develop for Linux you better be prepared to ‘read the source code’ or be told to ‘read the source code’, because outside of that you will be more often than not stuck.

Quick Creation vs Open Source

But you see there have been times when I wanted to create something very quickly and have wasted obscene amounts of time with very small issues that would have taken 60 seconds for someone who either knew the solution already or had access to good documentation.
I was asked recently to sit down and type some material from a web site that would have taken us as a group months to complete. But I had Visual Studio and using C# I hacked together a program that went onto the website and copied the data off of the tags and put it into a file. The whole copying thing could then be completed by a computer in 10 minutes.

I struggled finding out how to find and copy multiple instances of a substring in a string. I know that there has got to be a standard way of doing it. In the end, I never did find the standard way, I just wrote a program that made an array of chars and using loops tested for the start substring, copied everything in between until the end substring. It was a quick and dirty but effective little program.

The problem is, how long would it have taken me to do that on Linux? Guys/Girls, we have got to get it together, when we write a library or create whatever, the job ain’t finished until someone else can follow it without ‘reading the source’. How many people do you really think are going to spend hours and hours going through source code, just trying to understand it when they need something built yesterday?

What the future of Linux could be!

As Balmer famously said “Developers – Developers – Developers”, they then went ahead and created some breathtakingly excellent development tools. Getting something working on Windows does not require a knowledge of the Microsoft tool chain as it does with GNU software. There is such a diversion from “look I’ve got this crazy great idea to build application x” you end up going down the road of “so how do I do this really simple basic thing? It’s not on Google, its not in the official documentation, it must be some sort of special secret, I am just not a geek enough!” But if I could easily find out how to create say new tabs on the fly with a dummy tab with the Gnome notebook API and it was really clear in the documentation (with examples) I would have created a bunch of things in my own spare time already, I know I would of, if you could lower the cost in terms of time, and if I would, then there are a LOT of people who would have, but we are missing out because too much time is required just working out the basics  or fixing the tools all the time.

Driving down the cost of free

Why is Open Source missing a great video editor/Photoshop replacement/Dreamweaver replacement/OneNote replacement? What is preventing something as mammoth as Open Source from reaching its potential to quite frankly dominate the software world and so take over the way we always believed it could? In answer – documentation for programmers.

Think about it – Open Source development, which can be paid but normally isn’t, depends upon these factors.

Low cost – in terms of:

Time (if its not paid, then people need to do something else to earn a living and need to keep time free)

Effort (This is linked to time really, as effort be it physical or mental takes time)

Price (If it is a hobby then costs need to be kept down)

The joke of the matter is that all these things apply just as equally if it is commercial development. Have you ever tried building a Hello World dialog box using an out of the box version of KDevelop – (latest version) on the current leading distributions? You should just create the project – made from a template and then build/run right? Man! It’s a painful experience using the KDE4 API’s. But using QT development tools it’s an absolute joy. Essentially make it easier to get stuff done and we will reward you.

Thanks for reading.