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.
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’
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.”
Loading ...
We have been addressing the user-level documentation in an indirect way for FOSS systems for those in academia. Our Scilab Textbook Companions (TBC) are collections of Scilab code for the solved problems of standard textbooks. Through community participation, we have created 400+ Scilab TBCs. This indirectly solves the documentation issue for Scilab for the users of these textbooks. In a similar way, we are creating TBC for Python and OpenFOAM. Another user-level documentation project "Spoken Tutorial" that we started four years ago has now become a massive training project. Although these efforts address the ongoing issue only indirectly, I am pointing these out with the suggestion that one need not look for conventional methods of documenting.
Ubuntuguide ( http://ubuntuguide.org ) and Kubuntuguide ( http://kubuntuguide.org ) have been around for over 7 years and are pretty extensive. Ubuntu itself has an extensive wiki as well.
Debian has an extensive wiki manual, as does Red Hat’s Fedora, OpenSuse, and CentOS, to name a few.
To say that there is no documentation is a bit ridiculous and to me sounds as if someone has an agenda.
So you can pay O’Reilly once a year for a book that will be incomplete and out of date due to the insanely fast software revisionism in Linux?
BTW its ironic that you said that since you are advocating for proprietary docs because that is exactly what the O’Reilly books are, proprietary.
I think of documentation in a similar way that others think of testing — black-box or white-box. In the black-box case, you cannot see inside the software. You can provide input and configuration settings, try to use it, inspect the results, and analyze the errors. Any documentation records all of that and repeats until the writer calls it d_o_n_e. Consider the forest of button, input and menu inventory documents out there as evidence of this approach. The white-box case works from the source code or very close proximity to those who doing the implementation. Are you surprized there are so few of these?
Those who are good technical writers likely don’t have the skills (or inclination) to work with the source code as their source of expertise. They do need access to subject-experts [aka, "the developers" or similar] for those questions that always come up: "Why did it do THAT?" "What is it SUPPOSED to do when __X__?" Sadly, the FOSS ecosystem has yet to find a way for writers to get answers from "experts" in any meaningful way.
I know. I’ve tried. I’ve been a tech writer for almost ten years now. Over the years, I’ve tried to create documents a few FOSS projects. I got minimal responses from "the developers."
Back in my developer days, we started with a file that presented a summary of the application benefits to the end-user along with the features needed to deliver those benefits. Next came man pages for every executable and protocol. We wrote the main progam using the man pages as spec. As we needed libraries, we wrote those man pages then the code for each library. All along, someone was tasked to keep that original summary consistent with what was getting built.
While many FOSS projects have "blueprint" and other documents that describe existing and planned features, these only serve a writer with material for an outline at best. Until there is a channel for writers to ask questions and get answers from "experts" — not "the community" — documentation will remain a second cousin if not second citizen.
I’d like to add my $.02 and say that I agree with most of the article. Unfortunately people keep saying that documentation isn’t ‘fun’ – that’s not really true, at least for me. I’ve created a good reputation based on my ability to document things from analysis thru design, development and then writing systems and user manuals and tutorials.
Someone made a remark that the large corporations should hire a flock of testers and writers to do the job for the larger most popular apps. One of my favorites for docs is Oracle Corp. Their virtualbox documentation is excellent, and is updated with every point release of the software.
Their database docs are legion, even though they aren’t open source but are freely available to anyone wishing to study or reference their products.
I treat doing documentation as a project – requiring a certain kind of planning – and analysis, design, prototyping, then writing, testing and publishing. I call this "programming maturity", not unlike the phenomenon of math maturity that a lot people hit in their teens.
If anyone is interested, I’ll write documentation for $30 / hour. I’m retired now and have extra time that I can use to research and write.
Regards,
Steve Dupuis
Ottawa, Canada
Quality documentation for Open Source software exists and you can buy it from O’Reilly and other publishers.