Why open source software (FOSS) struggles for acceptance

I like open source stuff, for a variety of reasons. I like the philosophy behind it, and I like the idea of many eyes and many hands working together to create better things. While I do understand that there are situations where open source is not appropriate, such as with the proprietary things I work on in my day job, I also believe that there are many cases where open source is not only appropriate, but necessary.

Software is a case in point for open source. With open source software there is less likelihood that someone will slip a nefarious backdoor into an application, and the overall “attack surface” (as the security folks call it) is much smaller than with closed applications. Free open-source software (FOSS) also has the benefit of multiple eyes reviewing it, finding bugs, suggesting (or creating) improvements, and serving as inspiration for other projects. But there are two problems with open-source software that I believe will be fatal in the long run: The documentation sucks, and the attitude of some of the people who write FOSS does nothing to help the cause. I believe that these two things are closely related.

In addition to being a software and hardware engineer, I’ve also paid the bills as a professional technical writer and illustrator. So I know that writing a technical manual is hard work. And it can be deadly boring.

But, consider this: If you go to the trouble to create something like, say, a library or a maybe an application of some type, don’t you want people to be able to use it? If not, then why did you even bother to make it available in the first place? Sure, not everyone may be as smart and clever as you might be, but does that mean they should have to read the source code and reverse engineer the API to figure out how to use your creation?

At the very least that is just lazy and inconsiderate. At worst it’s nothing less than evil arrogance and contempt. Unfortunately an attitude somewhere between these is how most FOSS comes off to many people who attempt to use it. Consider this: If FOSS was well documented, would O’Reilly even be in business? Tim O’Reilly started out with the “missing manual” series of books, and they served a very important need: Lack of documentation. And O’Reilly isn’t the only publisher who cashed in on this problem. Even commercial software products like Word, Visio, Windows, AutoCAD, and many others have after-market books available to try to help fill the gaps that the official manuals don’t cover (or don’t cover very well).

Now, you would think that a big software company would understand that the pretty GUI is only half the user experience. The documentation is what really makes or breaks it for the user. It doesn’t matter how clever, sophisticated, novel, or pretty the software might be, if the user can’t figure out how to use it the way they want to use it, then they will likely move on to something else as soon as possible.

The documentation is like the kindly older person who takes the time to show the new person the ropes, and it needs to do this without putting the user to sleep while they read the manual, or being too condescending and pedantic. That’s a tough balance to find, and it’s tough to maintain throughout a manual.

With FOSS the problem is not just badly written documentation, it’s often a lack of any meaningful documentation at all. Now, before you jump up and down and yell “man pages” at me, just let me say that I love man pages. I’ve been using Unix and Unix-like systems since Version 7, and I appreciate a concise, well-written man page. But I would wager that most users of Linux (or FreeBSD, or Solaris, or whatever) don’t have that historical background. To them, a man page looks like a lot of acronym-babble and cryptic jargon. But to the people who create the software a man page is perfectly fine. They are comfortable with the environment and they know the jargon. Unfortunately they also assume that anyone else using their software will know it as well. This is one of the roots of the problem.

Another part of the problem with FOSS documentation is that, sadly, many programmers and software engineers seem to incapable of writing. I can’t say that they are illiterate, but I’ve sometimes wondered about that. Here’s a story: I once taught classes on safety-critical software testing techniques. The final assignment was to create a test plan document. It was fairly simple, maybe 20 or so requirements that needed corresponding test cases and test procedures, along with a basic plan to bind them all into a cohesive set. All-in-all about 20 pages or so. I figured it to be about four or five evenings worth of work. It didn’t have to be NASA or FAA level of detail, and a lot of it involved copy-paste from existing templates.

Imagine my surprise when only part of the class actually managed to write anything at all. It wasn’t that they didn’t know what was involved, or how to read a document like that. They did well on the exams, asked good questions in class, and generally seemed like a bright group of people. But, they either couldn’t, or wouldn’t, write. This same situation occurred in other classes as well. Engineers struggled with design and requirements documents, software people couldn’t write end-user documentation, and too often what was written looked like something created by a grade-school child. Sadly, I still see this happening today.

Lastly, there’s plain old arrogance. Nothing infuriates me like reading (or hearing) someone stating “just read the code.” Well, screw that. I don’t have time to read the code, and I don’t care how cool or clever the author thinks it is. I just need to get something accomplished, and if the software in question isn’t helping me to get there, then I will look for something that is. Even if I have to pay money for it.

For example, I recently found a GNU package that I really wanted to use on a project. It had all the right stuff, and it did the right things. The problem is that while it came with a library and a suite of command-line utilities, the library is totally undocumented. There aren’t even enough comments in the source code for Doxygen to extract something useful. I found a response from the author about this issue, and I’m still baffled by what I read. It was basically incoherent. The only conclusion that I could come to was that the author was saying: This is my wonderful software, and if you need to know how to use the library API, then just read the include file. The author then goes on to admit that the comments in the include file are terse, he isn’t interested in writing something like a reference document, and he can’t be bothered to figure out how to use a tool like Doxygen.

So, we have two basic problems: Badly written documentation and lack of documentation. The first could be solved with a little effort and maybe some writing classes (or hire a professional technical writer). The second is more difficult. If a software developer cannot write documentation, for whatever reason, then they really should consider enlisting the help of someone who can. If the software developer believes that anyone who can’t figure out the details from examining the terse man pages or browsing the sources should not be using the software, then I would suggest that they consider an alternate career. Or find a job where they can hide out in a back room and have some pizza kicked under the door occasionally.

Put these things together and it’s no wonder that FOSS has something of a reputation as being poorly documented and hard to understand, and so by extension it will be difficult to use and difficult to configure. Sadly, this is often true. Another perception is that FOSS is often developed and maintained by arrogant, unpleasant people with little patience for those less knowledgeable than themselves. I know that’s not true for all FOSS developers, but it’s true for enough that the rest may be tainted by association.

So if the FOSS community wants to see more people use their operating systems and applications, then they really need to ditch the holier-than-thou image (the smug Gnu, really?), learn some people skills, and start writing documentation that people can use.

Otherwise people will continue to do what I’m about to do with the GNU application I don’t have time to reverse engineer: I’m going to find something else to do the job, even if I have to pay money to get it.


0 Responses to “Why open source software (FOSS) struggles for acceptance”

  1. Leave a Comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

Follow Crankycode on WordPress.com

Little Buddy

An awesome little friend

Jordi the Sheltie passed away in 2008 at the ripe old age of 14. He was the most awesome dog I've ever known.


%d bloggers like this: