Showcase Your Business as a Thought Leader - Publish Your Blog, Videos and Events on ALL EC - Save 25% Now
Welcome Guest | Sign In

FOSS' Documentation Dilemma

By Katherine Noyes
Aug 11, 2014 4:33 PM PT

Hang around for any length of time in the seedy bars and watering holes of the Linux blogosphere, and you'll soon realize that certain topics tend to recur with surprising frequency in the general conversation.

FOSS' Documentation Dilemma

The most obvious example, of course, is the Year of Linux on the Desktop -- a topic scientists have determined will surely outlive us all. Then, too, there's the Sexism in FOSS topic, which one can only hope will become moot in not too very long.

The latest example to rear its less-than-entirely-attractive head? That would be the FOSS Documentation Dilemma -- or, more precisely, the Lack of Good FOSS Documentation Debate.

'I'm Aghast'

Linux Girl

It's been a few years since the Documentation Dilemma was featured prominently here in the Linux Blog Safari, but it seems safe to say that it's never too far below the surface.

Just last week, however, it reappeared in no less prominent a venue than Slashdot.

"What To Do About the Sorry State of FOSS Documentation?" is the title of the Ask Slashdot post that brought the topic to light once again, and the Linux-loving masses have been swarming ever since.

"I've been out of computers as a serious home-hobby for many years, and in returning, I'm aghast at the state of documentation for Open Source projects," wrote Slashdot poster TWX.

"The software itself has changed significantly in the last decade, but the documentation has failed to keep pace; most of what I'm finding applies to versions long since passed or were the exact same documents from when I dropped-out of hobbyist computing years ago," TWX said.

More than 400 comments later, Linux Girl finally reclaimed her favorite barstool down at the blogosphere's crowded Punchy Penguin Saloon. Tequila Tux cocktail in hand, she whipped out her Quick Quotes Quill and began taking notes.

'They Want to Just Write the Code'

"I think this represents a weakness in the Open Source model," suggested Google+ blogger Kevin O'Brien.

"Most things that happen in Open Source do so because of someone 'scratching an itch,' and very rarely is that itch that documentation needs to be improved," O'Brien explained.

Good documentation requires "close cooperation between the developers and the writers, who have different skill sets and don't speak the same language," he pointed out. "And will the developers take time away from coding to spend time with writers? Often, they don't think they should. They want to just write the code, throw it over the wall, and let someone else deal with documenting it."

'FOSS Documentation Will Always Lag'

Indeed, "FOSS programming is fun -- it's rewarding," agreed Linux Rants blogger Mike Stone. "If you create something great, people recognize your name, your brilliance."

Documentation, on the other hand, "is none of that," he pointed out. "When you're doing a project for fun, it's hard to be motivated to do something that's not fun or rewarding."

As a result, "I think FOSS documentation will always lag behind FOSS software," Stone opined.

'A Good Place for the Linux Foundation'

"I think the only way it can improve is for some corporate entity to hire people to do it -- IBM or Red Hat or Canonical or someone similar," he suggested. "Hire a significantly sized group of people to do nothing but contact developers and develop documentation for the applications people use."

Otherwise, "I just don't see FOSS documentation keeping up with development -- ever," Stone concluded.

"This would be a very good place for the Linux Foundation to step in," offered consultant and Slashdot blogger Gerhard Mack.

'Make Documentation Proprietary'

SoylentNews blogger hairyfeet took a more extreme approach.

"The answer is simple: 'Free as in beer' needs to die -- it's holding back FOSS," hairyfeet said. "You simply don't get quality work done by people who are only doing it on the weekends, and if you are doing a project on your own free time, what is the incentive to write docs? After all, YOU know how to use it!"

So, "the F in FOSS needs to go or be strictly 'free as in freedom,' with the distros taking the money they are paid for their product to hire everything from doc writers to bug testers," he advised.

"Since I'm sure many will balk at this, the only other answer that will get results is just as simple ... make documentation proprietary so that those that write the docs can profit from their endless hours of hard work," hairyfeet added.

'Google Is Your Friend'

It's true that documentation is "scarce in some places in the world of FLOSS," blogger Robert Pogson told Linux Girl.

"Distros like Debian GNU/Linux have a lot of 'man' pages, which helps get things going, and many configuration files contain comments," Pogson pointed out. "Fortunately for end users, GUIs are rather obvious, and many contain online help. The real geeks amongst us can look at the code..."

Sticking with "the most used and best applications," meanwhile, helps ensure that "there will be good documentation and help online," he added.

In reality, though, "most of us are too busy to read any documentation," Pogson asserted. "It just slows us down.

"For software, the application had better be self-documenting or work intuitively," he said. "Otherwise I would not use it. With a GUI and actual menus, one points and clicks and sees what happens. If there's something you want to happen but don't know how, Google is your friend."

In short, "while more and better documentation would be a good thing, it is not essential to the health of FLOSS or IT using FLOSS," Pogson concluded.

"If anything is really deficient, users or developers can rapidly fix that," he said. "Feedback from users is key -- users can get organized and create documentation or they can inspire developers to produce more. It's all good."

Katherine Noyes is always on duty in her role as Linux Girl, whose cape she has worn since 2007. A mild-mannered journalist by day, she spends her evenings haunting the seedy bars and watering holes of the Linux blogosphere in search of the latest gossip. You can also find her on Twitter and Google+.

Facebook Twitter LinkedIn Google+ RSS
Freshsales - Your salesforce deserves better CRM
What do you think of commercial spaceflight?
It's the best hope for advancing space exploration.
It's little more than a hobby for billionaires.
It will result in highly profitable new industries, like space mining.
It will dramatically increase space junk and pollution.
It will offer the opportunity to establish a new way of life in space colonies.
It should be heavily regulated by governments.