I tried coming up with a nice story or a cool introduction for this post. Perhaps a story about puzzles, or the stereotype of men throwing out the manual of a new product. To be honest, however, I just want to rant for a bit about some of the “documentation” out there. To make matters worse, this rant is brought to you by niche Open Source software which could they could replace by a cloud solution which would have done a better job. But that’s beside the point.
Last week I was working on a project, trying to get an application to play nice with another application on a Linux server.
I’m not a Linux expert. Nor do I have particularly strong feelings for Linux. That will probably never change since I never bought into the “Open Source is best” ideology. But sometimes, there are things that need are done on a Linux Server. Things I need to do. In most cases, I manage just fine.
It’s when it comes to actually configuring Linux applications that things get frustrating, because half of the time, the documentation sucks.
And boy, does the documentation suck for this particular software. The official documentation was hard to read and made some pretty huge assumptions and never explained concepts properly. In order to get the solution running I needed to Google the puzzle together. Google is often my friend, but in this case it was complicated.
As is often the case with Open Source, the “solutions” for the problems I encountered were all over the place. Quite literally, too. I had to puzzle together comments from Forums, StackExchange questions and blog posts and pick the pieces I thought I needed to find a final solution for my problem.
In the end I got it to work, but not before I decided to scrap an entire “branch” of documentation that I was following. It turns out that there was a completely different way of doing the same thing, which solved my problem. While the “solution” I had started to follow from the beginning, ended up failing.
I’m not sure if there is an “idea” behind this blog post, other than to complain that some Open Source software seriously lacks in “final documentation”. In Open Source, the idea that “You need to figure it out yourself” seems to be really strong.
A Business Opportunity
There is a lot of documentation on the internet. Lots of it is in poor shape or spread out over dozens of websites. I imagine there would be a real business opportunity writing some real good documentation for the Open Source software that’s lacking. I now also understand why some people prefer to use “commercial” Open Source over the free Wild West variety.
Don’t look at me to solve the problem, though. I will happily admit that I am not the kind of person to shell out documentation for an Open Source solution. I’m not that invested in the Open Source philosophy.
However, this experience made me revisit an idea I had a while ago called DIYoomla. I don’t want to give away too much, but I am planning to write and / or centralize some documentation for software that’s dear to me. Software of which I feel I could write some decent documentation. To fill the gaps that the official documentation left behind. But, more specifically, to help people with specific scenarios that the official documentation doesn’t cover for the simple reason that it’d be too much for the average user.
The name probably already gives away what direction I’ll be thinking of. And no, war hawks of FOSS, it’s not a trademark violation. It’s a clever play of words.