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.” Telling users and potential contributors to use Google, mailing lists, and forums is not documentation. It’s a way to guarantee having fewer users, unhappy users, and fewer contributors.
Let me share with you how I spent much of the past week. (Lately I’ve been spending a lot of time wrestling with application problems; this is just one example.) A certain application that I use every day was failing on one command and returning this fine unhelpful error message:
Finished with exit status 1
Oh goody, how illuminating. So I look in the man page and none of the error codes are explained. The command does not generate any logfile entries. Good so far, a promising start. Next stop, Google. Google finds a fair number of other users with the same problem, but no solution.
After some more attempts to figure it out (trawling mailings lists, pestering friends, sending out the bloodhounds) I give up and contact the developers. I get a reply, yay! The short story is the dev wanted to know what the logfile said. I’d already said there was nothing in the logfile. I tried it again and looked for other secret logfiles, and checked the syslogs. Still nothing. I wrote back explaining this and asking for more debugging advice or any other useful pointers. No reply yet.
I might file a bug report for the amusement of watching it grow cobwebs. But I’m not even sure where to file a bug report– with the application’s project site? The Linux distribution I am using? The upstream of my distro?
At this point I still have a few options: learn how to code and debug, and fix it myself. Keep badgering the developers. Try a different version. I went with C, using an older version of the application on a different Linux on a different PC. That worked. It took the best part of a day to get the settings where they needed to be, and to make a few changes to my documents and scripts to compensate for being on an older version, but at least I can get my work done. Provided I don’t encounter any more showstopping errors.
Desktop Linux Can’t Survive This
This is a popular application, not some weird little niche thing. Maybe the core problem is not strictly a shortage of developer time or people willing to devote themselves to coaxing coherence out of devs so they can write the documentation. Maybe the core problem is inefficiency and duplication of effort. Desktop Linux users are very dependent on their chosen distributions for everything– correct builds and packaging, updates and security fixes, and bug tracking and fixing. Servers are much simpler: no Xorg or graphics hassles, no multitude of applications, just a few specialized tasks and lean installations.
Desktops, on the other hand, have to absorb everything from basic email and Web surfing to multimedia production, office productivity, accounting, games, science and educational apps, programming and script-writing, all kinds of networking tasks, you name it we want it.
So maybe the distro-does-all model is not the best one. Application developers wail about having to support multiple Linux versions, but in some ways that makes a lot more sense than building giant teams to manage thousands of packages for a single distro. When there is a problem we will know exactly who to talk to and have a single master bugtracker and information resource, instead of getting the “Not our problem, go bother upstream” shuffle. Applications will look and behave the same across distros instead of being plagued with bizarre distro customizations. One of the best features of the top Linux distributions is having trusted repositories and a single installation interface; is it so farfetched to imagine the original developers of applications integrated into this? They know the code better than anyone; who better to manage bugs and distro integration?
Continuing this rosy, idealized scenario it would then be possible for the application’s developers to write and maintain a single authoritative manual. Oh I know, elite coders are savants who can only do one thing, and can’t possibly be expected to be writers too. (Unlike the rest of humanity, who somehow manage to acquire multiple skill sets.) But at the very least I would like to see a complete command reference. That’s right, a good old-fashioned man page with all commands, options, messages, files, and error codes. That is a great basis for other documentation writers to build on, and should be given equal importance to writing good code.
Supporting a gazillion distributions is not possible, but how about supporting the major ones? Debian, Fedora, openSUSE, Mandriva. Most others are derivatives of those four. Make packages for the parents and let the children fend for themselves. Gentoo and Slackware optional, though once again they both have many derivatives so supporting those two means supporting a whole lot more with the same amount of effort.
Recognize That Coding is Just the Beginning
There’s this whole coder-rock-star thing that is just plain weird. What good is code with bugs? What good is code that nobody knows how to use or understand? We like to mock the Microsoft ecosystem for being a haven of useless parasites that profit from its defects. I made a good living for many years writing Linux howtos and doing Linux training, most of which I felt should have been unnecessary because the bulk of it had to address basic functionality. Is that really better?