Documenting bugs

I hate having to write about bugs in the documentation. It feels like waving a big flag that says ‘Ok, we suck a bit’.

Today, it’s the way fonts are installed, or rather, they aren’t. The Fonts folder doesn’t show the new font, and the applications that are already running don’t see them.

So I’ve fixed the bug that was filed against the documentation. Now it’s up to someone else to fix the bugs in Gnome.

Choice and flexibility: bad for docs

Eye of Gnome comes with some nifty features like support for EXIF data in jpegs. But this depends on a library that isn’t a part of Gnome.

So what do I write in the user manual for EOG?

‘You can see EXIF data for an image, but you need to check the innards of your system first.’
‘You can maybe see EXIF data. I don’t know. Ask your distro.’
‘If you can’t see EXIF data, install the libexif library. I’m sorry, I can’t tell you how you can do that as I don’t know what sort of system you’re running Gnome on.’

The way GNU/Linux systems are put together is perhaps great for people who want unlimited ability to customize and choose. But it makes it very hard to write good documentation. In this sort of scenario, I would say it makes it impossible, and we’re left with a user manual that looks bad.

I’ve added this to the list of use cases for Project Mallard, but I don’t think it’ll be an easy one to solve.

World Domination!

Very interesting survey results from Federico.

I’m particularly interested by the section on Usability and Navigation.

“Users who tried KDE found themselves unable to effectively work with Konqueror.”

“One has to remember that these are everyday people who are having trouble, not hackers. People don’t understand hierarchical file systems at first, and simply put everything in the default location.”

This may be hard for people like us to get our heads round, but we have to. Real people out there, who are perfectly intelligent, just don’t get most of the concepts we take for granted.

Slow bugs

I was going to write something well thought-out about open source, the Cathedral and the Bazaar, and all that.

But I’ll just cut to the chase: why does it sometimes take years to fix what look like simple bugs?

Bug or feature?

Someone’s jsut told me that this is a feature.

Please no. It makes any work I do with GNOME a pain. Any time I work with HTML or DocBook, moving lines or blocks of text is a nightmare, as they glue to the next one, and there’s indentation spaces that get mixed in there too.

Can’t non-geeks use GNOME too? Do you guys really not want us around? It would be simpler if people jsut told me to fuck off.

On the dark side…

Just to show that I don’t only complain about problems with GNOME and free software, I’ll tell you about about a recent problem with MS Word.

I had a document, let’s say 12 pages long. There was a section break at page 10, because the final two pages needed a different footer. More specifically, they needed their own page numbering.

I wanted to print just the last two pages, so I typed ’11-12′ into the print dialog’s page range field. Nothing happened: just the little printer animation on the status bar, and then nothing. I tried ‘11,12’. I tried a test page to see my printer hadn’t just died. Still nothing.

Apparently, if you restart the numbering in your headers and footers, Word can no longer print the ‘real’ page number. Even though the status bar tells me I’m looking at page 11, the print dialog doesn’t recognize that number. Nor does it give you an error message about it. That would be too simple!

I opened the same document in, hit Print, typed in ’11-12′, and bingo, there it was coming out of my printer’s tray. Just perfect.

I guess the difference between Free software and non-free (or Microsoft) is that we gripe about Microsoft, but we know we’re powerless to get it fixed. We’re at the mercy of the next version, and who knows what that will bring. With Free software, there is the tantalizing possibility that the coders will listen, and the next version will fix the bug that annoys you. When that doesn’t happen, it’s paradoxically more frustrating than if there’d never been the hope of that at all. Basically, because Free software has so much more potential, its users are starting to demand more of it.

Bored now

I mentioned recently that I’m lacking time and motivation to do more work on docs.

There are several reasons for this.

Number one is the basic underlying problem with docs: it’s a largely thankless, unrewarding task. When you code, you get to enjoy the fruits of your labour as soon as you recompile your patched module. The improvements or bugfixes you made are there for you right away. When you translate, you have to wait until the next release, but you get to use a system in your own language. When you write docs… well, you know how the application works because you’ve spent days playing with it, so you probably won’t need to check the help for it.

So point one is that there’s little positive motivation.

However, there’s quite a heap of negative. I’m going to bunch it all together under the heading of ‘coder attitude’. I’m sure that many new and wonderful things are being worked on for 2.15, but I have no idea what they are. Nobody has yet troubled the docs list with an update. Perhaps they’re not ready yet, and if so, that’s OK. There is plenty of cleaning up work that I could be getting on with.

However, I feel no inclination to do any of this until this bug is fixed. To put it bluntly, I busted a gut writing the docs for the fileselector. It was hard work to get it clear and concise, and to cover everything it can do (and it can to a TON) in a logical manner that doesn’t overwhelm, and get it done in time for 2.14. I hope I’ve done a good enough job, and I’d be glad of feedback.

So far, the response from the GTK team has been some mumbo-jumbo about introducing dependencies. Read my lips: I don’t care. That problem should have been thought about and resolved back when the fileselector dialog was first implemented.

So basically, at the moment, I can’t be bothered. On top of the fileselector business, I’m bored of having to fight geeks over trivialities that should be obvious, whether it’s insane label text in the screensaver, or mounting shares that don’t exist, or any of the million crack-brained design flaws in gimp. This isn’t fun.

Thinking about users

Some doctors are excellent at what they do. But their bedside manner is terrible. They know lots about medicine, but they don’t relate well to people at all, and come across as brusque, uncaring, and sometimes upset their patients.

Similarly, there are some coders who I’m sure are excellent at programming, but who don’t seem to give much thought to a user’s experience of the software they are creating.

Just something to think about.