Enterprise Linux Log

Nov 9 2007   11:04AM GMT

Does Ubuntu’s documentation stink?


Ubuntu documentationIt’s a day of blog subject line questions, apparently.

The subject line question is asked today because there’s apparently some concern over Gutsy Gibbon’s documentation. Gibbon is the latest release of Ubuntu, version 7.10, which came out last month to the usual fanfare associated with new Ubuntu releases.

That said, Carla Schroder, writing for Enterprise Networking Planet, has a bone to pick with Canonical and the Ubuntu development team over documentation:

Whatever anyone may think of Ubuntu, you can’t deny they’re busy little critters, stuffing all manner of new things into every release. Which is a splendid thing, and what would make it even better is if they documented all of these wonderful new things. And also the old things. I think it’s the worst of the major Linux distributions for documentation. I spent a considerable amount of time trying to find out what makes Ubuntu’s server kernel different from a desktop kernel, what exactly is the OEM installation, where is the online package search page, what’s new in this release, and what’s included in this release. www.ubuntu.com is poorly-organized and seems more marketing-oriented than informative.

In our overview of Linux support, then and now, from this earlier summer, we identified similar documentation concerns with Linux in general. To see that one of the signature distros (and by that I mean one of the most wildly popular ones outside of Red Hat and Novell) is suffering from poor documentation is troubling to say the least.

In 2003, systems administrator Pati Moss said some online Linux/OSS instructions are very “high level and difficult to decipher.” IT manager Rick Segeberg agreed: “Newbies to Linux (especially non-programmers) find it difficult to follow the very technical documentation and how-tos that are available,” he said. “Most of the technical documentation is done by technical people for technical people.”

So documentation can be too technical and difficult to decipher. Got it. In our overview this was still a “thorn in the side” of IT managers, but at least Red Hat and Novell had stepped up to offer paid, professional support. But with Ubuntu, however, things are apparently too sparse! Not a good sign when Mark Shuttleworth and company at Canonical are trying to get Ubuntu pre-installed on commodity hardware from vendors like Dell.

Schroder again (under the wonderful subject line, “Dammit, Jim, I need documentation!”):

The Ubuntu release notes are quite sparse, and they lump the server and desktop editions together. There are bug reports and workarounds, but where is the list of major and new features? AppArmor is a radically new inclusion, but the only mention of it is that it breaks printing. What is it, and what do you do with it? What are the kernel versions, and versions of major applications like Apache and … well, what exactly comes with this release? What hardware architectures are supported, and what are some of the specific issues for them? And so forth—just cruise the Debian and Fedora release notes to see how it should be done. In fact you can check out older Ubuntu release notes—the farther back you go, the more complete they are, though they’re still short of what they should be.

The problem here, it seems, is that the notes assume a lot on the part of the reader. Do I know what AppArmor is? Sure I do, but I write about OS’s like Novell SUSE Linux and I know that AppArmor has been included in that distro for quite some time.

A huge part of the Linux ecosystem is documentation. Ubuntu Server — at least for one columnist — comes up short: “It’s also typical to include batches of READMEs and CHANGES and other helpful documentation on installation CDs. Don’t bother looking on the Ubuntu Server CD for these, because there aren’t any. However, it does include the “Ubuntu Installation Guide”, which is actually the Debian Installation Guide with some minor modifications, such as changing “Debian” to “Ubuntu”, and adding useful links to online Ubuntu resources,” Schroder said.

Apparently the Ubuntu documentation is Debian stuff dressed up with Ubuntu branding. Sounds kind of like what CentOS does with Red Hat Enterprise Linux (in reverse, of course), but in this case it’s a bad thing. Enterprise users want enterprise level documentation with their Linux OS. If Canonical is truly serious about getting Ubuntu pre-installed on commodity hardware, they’d best be tweaking their docs … do you agree?

 Comment on this Post

There was an error processing your information. Please try again later.
Thanks. We'll let you know when a new response is added.
Send me notifications when other members comment.

Forgot Password

No problem! Submit your e-mail address below. We'll send you an e-mail containing your password.

Your password has been sent to:

Share this item with your network: