May 14, 2009

Help Files Should Help, Right?

Microsoft Documentation Sucks
God knows I've had my complaints about Microsoft documentation in the past. Often about manuals consisting mostly of descriptions of the following nature:
Threep Nardling
To nardle threeps, select the Threep tab and check the Nardling checkbox.
Frankly this kind of documentation is worse than useless - it elevates statement of the bleeding obvious to new heights, and frustrates all users with at least one eye and half a brain. If you don't know what a threep is, or when it might usefully be nardled, the implication is that you are in the wrong place (though quite where else you would be expected to go for this information escapes me).

Ubuntu/Gnome Documentation Sucks
That said, I hope I am setting myself up for a fall here. I've just installed a number of Ubuntu 8.04 virtuals (because I want to be compatible with a client environment, since you ask), and I have been having problems getting the network interfaces to behave. So I go to the help file for the GUI-based networking tool so kindly provided, and the main portion is filled with this sort of idiocy:

The really annoying piece is that I went to the help file to try and get an understanding of the roaming mode, only to discover that this steaming pile of placemarkers* masquerading as documentation contains zero mention of the one interface feature I needed to know about. They could at least have had a section saying "Check this box to put the interface into roaming mode".

I am really hoping that this documentation has improved a lot in the two versions of Ubuntu that have been released since 8.04. If not, then it's time somebody (either at the Gnome Foundation or at Canonical) started to give some serious attention to documentation. Help files that don't help are a major source of end-user frustration.

Somebody, please put me out of my misery and tell me that this nonsense is gone in more recent releases. Otherwise I might just have to go home and bang my head against the wall.

The Real Problem
All of this is merely subsidiary to the real issue, which is how to I get a VirtualBox Ubuntu guest running under a Windows Vista host to track changes in the Vista internet connectivity. It seems like every time I change locations I have to spend time tweaking settings on the virtuals, rebooting uselessly and generally poking things until I get them to work without any clear idea of the eventually successful strategy.

So, dear lazyweb, please help me. If there's a manual that explains this I'd be happy to make a donation to its author. The open source world should, in my less than humbe opinion, value good documentation as much as (or more than) good code. Once you get past the obvious, the docs help you more than the code.

* Admit it, you though I was going to write "dung" there, didn't you? I am trying to eschew the obvious.


David Goodger said...

I have 2 VirtualBox virtual machines: Ubuntu (Jaunty/9.04) and Sugar. Running on a Mac host, but that shouldn't make a difference... unless it does.

I have 2 network adapters enabled in each VM, connected to the wired Ethernet and the wireless adapter, both using the "Attached to: Bridged Network" option (one says "en0: Built-in Ethernet", the other "en1: AirPort"). On the VM side, the guest OS just sees two generic network adapters, and has no need to know what they're connected to. They're simply either up or down. I have never had to fiddle with the settings inside the VM.

What are your VM network settings?

René Dudfield said...


I feel your pain.

if you want to pay someone... Canonical offer paid support for Ubuntu.


mae said...

This all comes from the fact that some people thing Documentation is for idiots or someone was payed to write that and their bosses failed in their supervising.

By the way typo "Most of it was to"

Steve said...

@mae: thanks for the "typo" correction - in fact it was just wordiness on my part, but I have changed it to be more readable.

I eventually realized the major issue was the need to validate the virtual's network interface to the web-based authentication system!