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 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!
Loading ...
have you looked at FLOSS Manuals?
We have been going now for about 2 years and we have many many excellent docs about free software mostly in English (http://en.flossmanuals.net) but also we have an Finnish community (http://fi.flossmanuals.net) and a Farsi community (http://fa.flossmanuals.net) and also many manuals being translated into various languages (see http://translate.flossmanuals.net/write).
for the linux community there is much of interest, but probably most interesting is the excellent introduction to the command line manual which we produced in collaboration with the FSF:
http://en.flossmanuals.net/gnulinux
You can buy it here:
http://shop.fsf.org/
We produce community authored content and we often do this in 2-5 days. For example the following were produced in 5 days :
http://en.flossmanuals.net/civicrm
http://en.flossmanuals.net/CircumventionTools
http://en.flossmanuals.net/Inkscape
http://en.flossmanuals.net/opentranslationtools
http://en.flossmanuals.net/ardour/
http://en.flossmanuals.net/theoracookbook
http://en.flossmanuals.net/sugar
and the following were written in 2 days:
http://en.flossmanuals.net/gnulinux
http://en.flossmanuals.net/GSoCMentoringGuide
http://en.flossmanuals.net/firefox
We also produce books. All of the above are available in printed form (see bookstore on the right of the front page).
We also have produced books in other languages including the recent ‘How to Bypass Internet Censorship’ book ( http://objavi.flossmanuals.net/books/CircumventionToolsar-translate-2009.12.01-12.02.55.pdf ) which was printed in Arabic for the recent Arabic Bloggers conference (http://advocacy.globalvoicesonline.org/2009/12/05/2nd-arab-bloggers-meeting/) held in Beirut.
It is not enough to recruit experts (with or without pay) to write,
because they can’t keep up with changes–I found that out working on
books about Linux at O’Reilly. But it is not enough to ask the
community to contribute micro-documents–that causes everything comes
out disorganized and of wildly varying quality.
My most comprehensive article on the issues is:
http://praxagora.com/andyo/professional/community_author_collaboration.html
Much more for the curious at:
http://www.praxagora.com/community_documentation/
At FLOSS Manuals (http://flossmanuals.net/), where I volunteer, we’re
filling the gap with well-organized writing projects combining peer
review from the public with experts from various free software
packages. There’s a very active mailing list and a lot of highly
praised output on the web site.
I was hired for my first official tech support position because I could read the manual. Much of my IT learning curve was assisted or hampered by the manual. In over forty years of trying to make a living, the formal training got me started, but the manuals enabled me to keep the job and move on to the next.
Dear Katherine,
Re documentation – Amen!
– Please see "how to write computer programs"
at http://www.civilized.com/programming.html
(There may be a few other things there like the
little book on Lisp that you would enjoy.)
I AM increasing seeing very poor documentation even with commercial products in the IT industry. In fact, on a recent task with an expensive organization charting component, there was no documentation!
The issue has always been with us in the IT field but increasingly it is becoming directly related to the growing sociological issue of deteriorating education in the United States and as a result, lowered professional expectations in the work-place. Newly trained foreign workers are not helping the matter either, with their sloppy coding habits.
Whenever I release software, I always provide professional level documentation with an email address that can be used for the product’s support. Yes it takes time but it also demonstrates that you are committed to your product whether open-source or not. Good documentation is just part of the process.
However, creating good documentation takes time and effort, something that in the corporate environment is just not allocated for any longer. However, in the open-source community and the ISV community there really is no excuse for this situation.
To see a sample of what professional technical documentation should look like go to the link below and download the freely available component.
You will find a "CHM" file with a complete discussion on how to use the component.
http://tech-notes.info/2009/11/05/black-falcon-software-presents-sqlhelper-%E2%80%93-easy-to-use-net-sql-server-database-access-layer/
Well, you get what you paid for.
As a professional technical writer working for a large computer company, we are paid to write high quality documenation geared toward the professional programmer and system administrator.
Writing technical documentation is a full-time job. The downside of FOSS is that no one considers documentation.
Well, almost no one. I would recommend switching to OpenSolaris if you’ve got a problem with Linux documentation. The documentation is much better.
http://opensolaris.com/
no program or command without adequate documentation should be included in a distribution.
I agree at the minimum it should have a man and info page.
There is no substitution for good documentation and windows and Mac OSX has tons of it, along with video tutorials…