Advanced

Linux Bug #1: Bad Documentation

Posted by tuxchick on · 20 comments
Linux Today Blog; By Carla Schroder
Mail this story
Print this story

The Internet and Google have made FOSS developers lazy because they have made 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.

Full Story

  Nav
» Read more about: Story Type: Editorial; Groups: Community, Linux

» Get new stories by e-mail: nightly or as they are published

« Return to the newswire homepage

  Related stories
» More like this

Comments (20)

Case Study: Ubuntu

Out of interest I had a look at the structure in place at Ubuntu. First off this is a community project:

https://wiki.ubuntu.com/DocumentationTeam#Meetings

I frankly do not consider that adequate. Why isn't there at least a coordinator employed by Canonical?

Secondly if you look at their meetings log it is rather disturbing:

https://wiki.ubuntu.com/MeetingLogs/DocTeam

No meetings in 2006, 2007 and 2008. Is that for real? I checked out the log for their latest meeting in August:

https://wiki.ubuntu.com/DocumentationTeam#Meetings

Very thin stuff indeed including this gem:

"Status update on Kubuntu and Xubuntu documentation

ACTION: Defer to next meeting where Kubuntu/Xubuntu guy are around"

Ubuntu/Canonical can do better than that. Resting on your laurels of a very successful forum is not a recipe for future success in my mind.

And before anyone gets on my back about contributing, I would like to point out that I have lodged around 50 bugs on launchpad and had a substantial number sorted out in addition to having roughly 1000 posts on the forums.
There was some talk about documentation on a recent episode of the Ubuntu UK Podcast, but I'm so horribly behind on my podcast listening that I can't remember exactly which episode.

But it is true that documentation needs much more work.

Look at the BSDs (Open-, Free-, Net-, Dragonfly-) and do likewise -- that's what I recommend.
Perhaps the article has changed since you guys read it but I'm wondering how a complaint about the documentation for an application became an indictment of (once again) Ubuntu/Canonical.

First off the documentation for an application is the responsibilty of the application developer. Full stop. It is not the responsibility of the distribution.

As for Ubuntu related documentation, have you actually looked at the https://help.ubuntu.com/9.10/ ? It seems to me they cover pretty much everything a user (particularly a new user) would need to know.

And before anyone gets on my back about contributing...

You won't get that from me. I'm even inclined to say that even if one wanted to contribute, not everybody is a gifted writer of end user documentation.

Canonical should put in some effort to get a documentation team working alongside of the devs. Outsourcing to end users is not a solution.

SuSe had excellent books in the boxed set back in the day. Don't know if Novell SUSE still does that, but those books were very valuable back then.
Cabreh, I like Ubuntu. Indeed I have it on 5 boxes all at the latest version and everything is working fine. I have been a Ubuntu user since warty. I also dislike moronic Ubuntu bashers.

That doesn't mean however that I should be uncritical when something is not right. You have a point about application developers being responsible for documentation but four things are relevant in response:

1) Several of the software changes I mentioned were made directly by Ubuntu developers. In particular upstart and the xorg changes.

2) It is all too easy to avoid responsibility by placing the onus on users or upstream. Canonical claims to be the leading Linux distributor. They also excuse their lack of contribution to the kernel by saying they contribute a lot in the desktop stack and userspace. Given that they should show more responsibility by chasing up important upstream documentation holes.

3) As caitlyn pointed out elsewhere, Red Hat has excellent docs. Why not Ubuntu?

4) As a long term Ubuntu user I have looked extensively at all their documentation including the link you provided. Your linked documentation is fine for newbies experiencing minor annoyances in their transition from Windows. It is not fine if you want/need technical detail in the event you are troubleshooting significant problems. In that case you usually (in my experience) have to rely on what other users have found out by trial and error either on launchpad or the forums. The developers are really little help here usually unless you are a paying customer of Canonical.
I'm with Montezuma on this one. I've praised Canonical when they've deserved praise. I've noted that on my hardware Ubuntu 9.10 (Karmic Koala) has been brilliant. I've also criticized when they've done an inadequate job or released a bug-filled mess. I'd put their documentation in the inadequate category. What's there is good but it's nowehere near what it should be in terms of content. Heck, Vector Linux does a better job than Canonical with volunteers and few resources.

I also agree that Red Hat is the gold standard among Linux distributions when it comes to docs. I can understand if a small, hobbyist distro can't meet that kind of standard. It's one of the reasons I don't depend on little distros built in someone's free time no matter how well done they are. When it comes to corporate Linux, including Novell, Canonical and also smaller for-profit entities like Mandriva, Xandros and Linpus, they really do need to deliver comprehensive documentation with each release.
Example:

While Ubuntu's NetworkManager 0.7 page https://help.ubuntu.com/community/NetworkManager0.7 is better than the project's own site http://projects.gnome.org/NetworkManager/ by more than a few leaps and bounds, the Ubuntu page is far from complete and up-to-date:

Quoting:c. Specifically for Intrepid and later, if your interfaces are shown as "unmanaged" in network manager applet, please read the troubleshooting section about "TBD" or "To be defined"


I found my solution to this problem in a Debian bug report: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=517194

Amen and Amen again, sister.

I recently had the pleasure of dealing with nitty-gritty issues in the Joomla! CMS, which just about made me pull my hair out.

Joomla!, overall, is a nice CMS, but... like Ruby on Rails (another source of lost hair, though not quite as bad), full of conventions that just have to work, especially when you get into their interpretation of MVC.

Hint:

Simply providing an example and saying "This works" is not documentation. It's nice. It's a help, but...I probably need to do something different, and am likely to change something very early on. A little explanation of what things must follow what convention will save a lot of grief.

Oh yeah -- autogenerated listings of class structures are nice, but explanation and descriptions would be nicer.

Oh -- and for Pete's sake -- bringing the documentation together in an organized way is not a crime against humanity. Google and kin are great, but... the same key word can apply to user interactions, administrative entries, and --- gosh! --- development of new or extended functionality. Guess what's going to come up first, ad nauseum on the results lists? Hint: Probably not the stuff you're really looking for.

At least it's better than the libxml2 documentation, and we won't even go into Zope -- or, at least, the Zope of 5 or 6 years ago.

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.

Document, guys. It's what professionals do.

#2 & #3

Actually the article seems to be about more than '#1 documentation':

#2 Fragmentation / duplication of efforts because of distro's. Different distro's applying different patches to 'upstream' software, a lot of them fixing the same problems / adding the same features. All of them having different 'base-libraries/versions'. Therefore, it's almost impossible for 'upstream' to solve distro-specific issues.

My favourite writer (apart from his bashing / profane-words personality) has written about this many times, there's a summary "Down with the distro's":

http://modeemi.fi/~tuomov/ion/news/Down_with_the_distros.htm...

Daniël Robbins has exactly the same complains as of lately; willing to "rebuild" Gentoo more as Slackware / BSD "without all the Gentoo-isms" meaning lots of stuff only work for / in Gentoo. Supporting Gentoo as 'upstream' is nasty, not only because different setups, but also because of the tons of Gentoo-only patches applied by Gentoo.

#3 would be the absence of stable platforms to 'develop against'. Sure, there's Ubuntu LTS. But why is there no such thing as 'Linux-base'-LTS? Sure there's LSB, but sadly it's almos only supported by "the big three" (not including Canonical) and Ubuntu 6.04; not by the newest Ubuntu LTS. Just another thing Daniel Robbins is dreaming to solve BTW.

I wonder what would happen if all people doing distro-specific patches / fixes would start writing documentation? Probably the same as if all LXer forum spammers like me would start doing the same, but hey, the latter group is much smaller.

Nonetheless, we are told "this is part of Free Software", the adagio about "we don't want no one-fits-all mono-culture", "choice", and "If there's even only one person for which this distro is useful there's a place for it" and such. But what good is choice if we can only choose bug-ridden distro's? Why can't there just be one distro named "Linux?" (Note that would also immediately solve the assumed "Linux is no OS" and "It's GNU Linux" problem) Why is it easier to write software that works under any BSD - even if less people use it - than for Linux? Why am I the only one (or it seems to be) longing for packages which just work on any distro?

Therefore, I decided to "give up my ability to choose" and migrate from Gentoo to Kubuntu, because then my efforts of bugfixing (not much more than 6 posts a year or so, but anyway) would be more centralized, and I could better help other Linux users. Except that Kubuntu didn't work for me, caused by #2 and #3...

(If this sounds like a: "I-love-Linux,-I-even-use-it,-but... post: Yes, it is, and I've been a bit hesitant to "bash the Linux-ecosystem" before, but I become more and more fedup with it, especially given the way things could be, with the same amount of efforts.)
Hans, I've read Tuomo Valkonen's stuff before and at some levels he has a point. On the whole I tend to disagree with him.

I first ran into his license when someone asked for an Ion package for Vector Linux 5.8. At the time I was a volunteer packager for the distro. I read his license and politely explained why I couldn't build the package. I couldn't guarantee that I'd have time to build every update within 28 days of release and I couldn't saddle a relatively small, almost entirely volunteer packaging team with his terms. If the user couldn't compile Ion for himself he was out of luck.

IMHO Mr. Valkonen throws out the baby with the bathwater. He also fails to realize that for businesses having a single point of contact for support is vital. Having different projects point fingers at one another just won't cut it. Every time I write a review critical of some aspect of a distro the apologists blame upstream. Sorry, no, it's the distributor's responsibility to maintain the overall quality of the OS as a whole. The whole reason Linux can work for business is because Red Hat, Novell, Canonical, etc.. do not pass the buck. They take responsibility for their customer's needs. IMHO that benefits individual users as well.

The nature of FOSS and the licenses that the FSF have developed guarantee that there will never be a truly standard code base or a consolidated Linux base. To get there we'd have to become more like the proprietary software companies so many in the community rail against. It really is an either/or as far as I see it.

Are there too many half-baked, bug-ridden distros? Does Andrew Wyatt's "garbage salad" metaphor fit more than just Ubuntu? Nothing has changed since I wrote http://www.oreillynet.com/linux/blog/2007/01/so_many_distros... three years ago.
Of course there are plenty of reasons to disagree with Mr. Valkonen (and somebody not being able to package it was just his intention!), but he raises some interesting points. To a lot of them I agree (especially some of those about bicycles, but that's outside the scope of FOSS).

However I'm not that sure about 'one point of contact'.

Where I work we use software from Adobe, SAP, MS, PTC, Delcam, Dassault Solidworks (because of a lack of open standards!), Linguistic systems BV (that's the almost irreplaceable Euroglot) and Print2pdf from yet another company (and probably even more to come); and that's only my small 16 person department. Lot's of them don't interoperate - and were never designed to do so. There's not some single company doing all the support AFAIK, and everyone seems to be OK. And yes, cross-screwups between the software I mentioned happens. Last time it took someone two days to fix one such error, I was glad it took me only two hours before I found the solution which was documented (#1 uh?).

So nobody is doing any QC of "Windows as a whole" and still business is fine with it.
> So nobody is doing any QC of "Windows as a whole" and still business is fine with it.

Again, Hans, holding ourselves to the standard of Windows isn't good enough. We're supposed to be better than that.

That said, if you buy a commercial package for Linux (say, Oracle), that's who you expect to support it, not the distribution. The distribution supports the software they provide, not third party commercial software packages. Though from what I've heard, Red Hat goes above and beyond that standard and even works to resolve problems with third party software.
Quoting:Red Hat goes above and beyond that standard and even works to resolve problems with third party software.


So did Microsoft in the past, but not anymore.

Indeed, if I install a package for Linux and it's not vanilla (not patched by the distro), I'd suppose the one who build that application providing support and not my distro.

For example, I still have quirks with Firefox - and those are encountered on multiple distro's it seems. What's the use of solving this for Gentoo only?
Presumably Gentoo would report it back upstream Hans. I don't know how closely Gentoo works with upstream but Debian works pretty closely with it. They even adapted their BTS so it can cross-reference upstream bug trackers.

Personally I prefer to get bug reports and patches from downstream distro maintainers than directly from end-users. It usually makes fixing things a lot easier, especially when I don't have the distro around.

(On Debian, I maintain my own packages so I am both upstream as downstream).
Quoting:It usually makes fixing things a lot easier, especially when I don't have the distro around.


I'd agree, but it sounds like #3 again.

I was reading about LSB, but it seems to take quite some efforts to test your distro to see how much LSB compliant it is. Anyway, I might give it a try the next 24h I have nothing else to do.

After reading about the kit-trio (package / policy / device) I found some new hope about at least some unification (or is it interoperability?) between distro's. Together with LSB it's a nice effort I suppose.
caitlyn --

You must not have read the license very well. It provides a fairly reasonable alternative -- rename the package and remove references to Ion. Then you don't have to worry about any 28 days.

Burdensome? Don't know. Debian and Ubuntu do it with Firefox, so it must be doable.
Quoting:I'd agree, but it sounds like #3 again.


Not really. Gnome-hearts has been packaged and supported for many different distros without a single line of change. It's not that hard, really. And all I ever tested on aside my own machine was a not-quite-recent Ubuntu.

But for certain bugs you really want to try to duplicate the users environment. Sometimes bugs occur on one platform but not another. I ran into a really odd bug on Slackware once. Turns out that it was a bug in the Python packaging on Slackware. It's that kind of bugs that are easier to solve with distro maintainers than end users.
I was thinking about this issue, and what Caitlyn said about the "whole OS", jdixon about the 3d party software issues solved by the 3d party themselves, and what Sander said about gnome-hearts and distro specific bugs.

Then it occured to me that a 'better solution' might be the distro maintainers only caring for what's in the default install, and maybe not all 20k optional packages. Just like Microsoft does, but probably more work because most of the default Linux-installs contain more software than 'bare Windows'.

That way they can maintain the quality of the "OS as a whole", while not duplicating efforts for all 20k packages. I suppose I should try packagekit and find out more about LSB, though it seems both are quite hard to do on Gentoo.

Just some thoughts, not that it's going to solve any of the existing issues, but it might be a direction of some of my own (limited) actions.
Hans --

There is a hidden (maybe not so hidden) benefit to "core" distributions that cleave to certain standards.

It would make it much easier for projects to put up source, a deb, and an rpm. Sure would make it easier to keep the application you care about up to date without risking the stability of your system.
What I would really like to see is some kind of distributed bug/patch tracker. Systems like Git and Mercurial have mostly solved the issue of distributed development. But bug and patch tracking is still done in a very centralised way, like how code was managed with CVS. Every distro their own silo.

There are efforts to tie those together and make the silos talk to eachother (i.e. Bugilla can track remote bugs, as does Debian BTS) but we should do away with the silos all together.

With distributed bug and patch tracking I could track all gnome-hearts bugs globally and automatically. People writing patches for distro A could more easily share them with distro B, etcetera. I think a lot of duplicate work would be eliminated.

Same thing goes for package management by the way. We've had some discussions here about package management and duplication of effort. I don't thing that a universal package format or something like Klik is an answer to that. But distributed package management might, by tying together the maintainers for various distros in a non-centralised way.

Post a comment

A free account is needed to post. Write your comment here first: your text is kept in this browser while you sign up or log in, and is waiting for you when you come back.

Your message:
|||||
10
Markdown: **bold**, *italic*, [text](https://link), - lists, > quotes, $x^2$ for math. Formatting help

Sign up and post (it is free)  or  Log in and post