As Katherine Noyes points out in her blog entry found here, there is a lot of negative conversations around FLOSS documentation.  They also point out that the Open Source Community struggles with keeping up with documenting all the new tools which are constantly coming out. Is this really a problem though?

What do I mean?

Well, when was the last time you saw a good piece of documentation from Microsoft, or how about Apple? I do not mean that there is not any good documentation from the big IT Companies. At the same time, I can not say that there is not any good documentation for Open Source Software Community either. Both the “Professionally” created documents and Open Source documents, have about an equal chance of being good or bad. Katherine points to tons of articles written about Open Source misses. So here is my example of a large IT company’s miss.

I can tell you from personal and daily experience that there is a Mt. Everest sized pile of documentation around IBM’s WebSphere products. Sounds great right? What if I told you that 90%+ of it was useless or nearly useless.  A teammate and I recently spent 6 months designing, testing, and building out an upgrade plan from Websphere Application Server Version 6.0.x to Version 7. As we were preparing to start rolling out this upgrade, we fell flat on our face after tripping over a massive documentation miss on IBM’s part. We had put our plan in front of many people from IBM hoping to avoid any major issues and pull off a smooth upgrade.  All of those people missed the poorly documented items as well.  This oversight on thier part was so bad, that I received an E-Mail from them apologizing for their error.  In my 15 years as a person working in IT that was the first time I had ever heard of a company admitting it was their fault for a miss in documentation of any kind.  So IBM must have corrected such an oversight, correct?  I mean they have apologized and acknowledged the oversight. Yet, even after almost two months, IBM still has not corrected the missing and bad documentation.  So is this really a big closed source company doing it better?

To contrast that with my Open Source experience with Tomcat and Apache, I have never had a problem finding a solution from either the Apache.org Websites or by searching Google for one. Not all of the documentation I have needed in the past was created and hosted by the Apache.org team. Then again, not every document I have found useful for my struggles with purchased or closed source software has come from the companies themselves either. So why is either a bad thing? Why is one worse than the other?

O’Rielly and other companies exist and have created a large number of books sitting on my shelf only because the big companies and Open Source communities suck equally as bad at documentation. When I started my career in Linux/Unix as a Sendmail and Lotus Notes Administrator in 1995, I could not have survived without either my copy of the Sendmail book from O’Rielly or the Lotus Domino(Notes) System Administration book from New Riders. One Open Source and One Closed Source product and both with plenty of documentation online even back then.  Both were only use-able and manageable after using these books written by recognized experts in the software.

I am an open source proponent. If I was not,  I would not have started a site called linuxinstall.net. While I agree that Open Source documentation can and needs to improve, I do not agree that it is any better or worse than the closed source “competition”. I also do not think that telling everyone who writes documentation for Open Source projects that they suck or should work harder is a winning game plan either. If all of the people writing about how the documentation sucks, took the time and effort they spent writing the articles and spent it writing pieces of documentation for their favorite projects, we would have a lot more documentation.

The real problem facing all of the IT world is that it is not good enough to have a lot of documentation. We need to have a set of documentation that actually means something. Really good quality documentation is every bit as hard to write as the programs they are about. I know, I write a lot of documentation both for scripts I have written and software written by others consisting of both closed and open source.

If you are a Manager at any level reading this, and are still on the fence about Open Source Solutions, please hear this last point. The majority of all Open Source Documentation is better than the closed source competition. It has to be, because it does not have a big organization charging fees for support of their software and solutions on your systems. On top of that, the community around these software products almost always has zealots that will write documentation that when you read it, expresses their passion and knowledge of the subject matter. Not everyone who writes documentation has to be a technical writer, and not every document will ever be great. The beauty of Open Source Software is that there is almost always an alternative project that hopefully does documentation better if that is your problem.  Even better still is the ability to update the documentation yourself.  Once you figure out a solution, you can easily add it to most projects knowledge base with only minimal effort.

For everyone, do yourself and others a favor and either write or constructively comment on some amount of documentation every week. Start with one a week, one a month, or one a quarter. It really does not matter what the frequency is because what is important is that we all start doing it. We all need to start moving everyone away from talking about how bad the documentation is, and start talking about how great it is going to be when it’s finished.  Being positive will attract better authors and in turn increase the volume and quality of the collective documentation.

My questions to everyone who has read this are:

Do you think Open Source Documentation is stopping or slowing it’s adoption?

Have you ever written or constructively commented on a piece of documentation?(if so where is it let us all celebrate it.)

What do you think we should do as an Open Source Community to move our documentation forward?