Headline Feeds
There's nothing like weeks of ongoing conversation on the Linux blogs to suggest a topic has struck a chord.
Sure enough, that's exactly what's been going on since the middle of last month. The topic? Documentation. Not good documentation, mind you -- the bad kind. The kind Linux Today's Carla Schroder calls "Linux Bug #1."
"The Internet and Google (Nasdaq: GOOG) enable laziness in FOSS development because they make it too easy to abdicate the job of proper documentation to 'The community,'" Schroder began in a blog post a few weeks ago.
'A Good Old-Fashioned Man Page'
"Telling users and potential contributors to use Google, mailing lists, and forums is not documentation." Schroder charged. "It's a way to guarantee having fewer users, unhappy users, and fewer contributors."
At the very least, coders should create "a complete command reference" for what they create, she added.
"That's right, a good old-fashioned man page with all commands, options, messages, files, and error codes," she explained. "That is a great basis for other documentation writers to build on, and should be given equal importance to writing good code."
'It's Getting Worse'
Following a lively discussion both on Linux Today and LXer, where it soon got picked up as well, Schroder added a second installment on the topic over at Linux Planet.
Then, just this week, Linux Planet's Emery Fletcher chimed in with a user's perspective.
Is bad documentation holding Linux back? Bloggers have had lots to say.
"I've often said that one of the biggest problems with Linux is lack of easy-to-understand, readily-available docs," wrote jg on Linux Today, for example. "And it's getting worse ... out-of-date, obsolete docs. I recently tried to get a touchscreen working on Linux and went through hell."
'It's What Professionals Do'
Similarly: "There's a lot of great FOSS stuff out there, but nobody should have to be a mind reader or code God to deal with it," wrote dinotrac on LXer. "Document, guys. It's what professionals do."
Sensing that the topic was turning out to be bigger than it originally seemed, Linux Girl took to the streets of the blogosphere for more insight.
"I don't know why everyone expects coders to be great tech writers," Chris Travers, a Slashdot blogger who works on the LedgerSMB project, told LinuxInsider. "Yes, some things should be documented which aren't, but this is the case with all software.
"I think one thing we need to explore, though, is how to make technical writing economically feasible in the open source economy," Travers added.
'They Don't Even Read It'
"The only time I've been paid to do GOOD documentation was when it was going to be used to wow investors during the dot-com boom," Slashdot blogger Barbara Hudson told LinuxInsider. "Bosses nowadays don't seem to get that good documentation saves money."
Even worse, "when you document something, they don't even read it, even though they should," Hudson added.
Case in point: "Last year I spent two days doing 'Complete Documentation -- everything -- and it needs to be ready by Thursday' of the system we were working on," she explained. "123 pages worth, table of contents, footnotes, index, overview, the whole bit."
It was a week's worth of work done in two days, Hudson noted, but the result never got read.
"Why? 'Oh, it's too big,'" she recounted.
'I'm as Guilty as Anyone Else'
"The problem with documentation is that it's hard for the original developer to know what to document," Montreal consultant and Slashdot blogger Gerhard Mack told LinuxInsider. "We all know we need it, but we never know how to write it without being either too sparse or too verbose and covering the wrong things anyway.
"Since I'm as guilty of it as anyone else, I really don't have a solution to the problem," Mack added.
"I don't know how many times I've been told to RTFM only to find the RTFM has 'to be done later,'" Slashdot blogger hairyfeet said. "If the docs aren't done then the software isn't done and shouldn't be released."
Such situations make Linux look "like amateur hour," hairyfeet told LinuxInsider. "The days of the 'hobbyist' OS are over. Folks just don't have the time or the desire to learn the inner workings of an operating system."
'There Has to Be the Basic Information'
Indeed, newbies "cannot be expected to read the source code," blogger Robert Pogson agreed. "There has to be the basic information where everyone can find it."
The solution, Pogson added, "is for we who use the code to document it as best we can."
In other words, "we need more users of FLOSS to give back by writing decent, usable documentation," he opined.
Pogson himself plans to do "a lot of writing in retirement," he told LinuxInsider.
Calling All FOSS Users
"It can be done: examples, examples, examples," he asserted. "When there are too many options, parameters and commands, examples cut through the noise to the cases most people need and the usage becomes clear."
For large GUI apps, meanwhile, "screenshots are big," Pogson added. "One picture is worth a thousand words."
Hear that, dear readers? It's a call to arms -- or rather, a call to keyboards. Let the documentation begin!
Talkback: 
