Case Study: Ubuntu

Story: Linux Bug #1: Bad DocumentationTotal Replies: 6
Author Content
montezuma

Nov 17, 2009
9:56 PM EST
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.
Steven_Rosenber

Nov 17, 2009
10:07 PM EST
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.
cabreh

Nov 18, 2009
3:57 AM EST
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.

r_a_trip

Nov 18, 2009
6:24 AM EST
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.
montezuma

Nov 18, 2009
8:22 AM EST
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.
caitlyn

Nov 18, 2009
12:30 PM EST
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.
Steven_Rosenber

Nov 18, 2009
1:09 PM EST
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

Posting in this forum is limited to members of the group: [ForumMods, SITEADMINS, MEMBERS.]

Becoming a member of LXer is easy and free. Join Us!