I got a few interesting responses to my last post.

Apparently I’m just a freak of nature who can sit down and write some fairly comprehensive documentation as a single task, whereas with coding, I often find it necessary (or at least beneficial) to take a break, go away and properly think about what I’m doing or trying to do.

People quoted reasons such as finding it hard to write documentation which is easy to follow, it just not being fun, reminding them of schoolwork, etc… Also, those with non-english nationality pointed out that they find it very hard to write documentation in (good) English and wouldn’t see as much recognition if it was only written in other languages.

I guess that answers my question. Still, my point remains, documentation is a very rewarding contribution in terms of direct feedback.

I’ve been thinking lately about documentation for open-source projects.

Most of my open-source contributions are code-based, but occasionally I write or contribute to documentation. Yet the email feedback I recieve is pretty much 100% about documentation that I have written as opposed to code I have developed. I get people just saying ‘thanks’, people giving suggestions, people asking permission to republish it elsewhere, people providing translations, its fantastic and much appreciated.

I had a recent conversation with roger55 on IRC which went something like:

<roger55> hey dsd, i just got back from linuxtage graz, it seems you have a few fans out here
<dsd> roger55: cool! what were they saying?
<roger55> dsd: they love the guides you write

ahem.. I write lots of code as well!! ;)

The documentation/documentation-user seems to be a much more thriving and active community than the developer/software-user community, and from my perspective, documentation authors get a lot more feedback and direct communication with the users. Writing documentation for an open-source project is an exciting and valuable contribution you can make. Tag your email address on the end and you’ll really know when people are benefitting from your work.

The question I am posing: Why are there so few open source documentation writers in comparison to software developers? Using Gentoo as an example, we have just 15-20 core documentation writers, compared to hundreds of developers who deal with software code and maintenance. Not using Gentoo as an example, many open source projects lack comprehensive and up-to-date documentation, and a lot of existing documentation is written by software developers who write it in response to being asked the same questions repeatedly.

Writing code is a specialist thing. In the UK, you don’t really get taught how to do it until your 14th year of full time education. It’s very technical and you need to be skilled and have a good knowledge of computers to be an effective developer.

Yet language and literacy is something you are taught throughout education and life, and using software is a daily thing for many people. No offense to the skilled documentation authors out there, but I don’t see it as such a specialist activity. So where is the mass of documentors, and do they know what they are missing out on?

Myself plus a small number of other Gentoo users/developers are planning a small meetup in central London on Friday (17th). If you’re interested in turning up, send me an email, and I’ll pass on the details.

It seems that we have a fairly even split of opinions on whether Planet Gentoo should be strictly for Gentoo and related topics, or whether it should be a full aggregation of more personal articles plus Gentoo articles too.

As a result of this, we’ve decided to launch a second site, Gentoo Universe, which will aggregate all articles (any topic) on participating developers weblogs. This will run alongside Planet Gentoo, which will still remain an aggregation for Gentoo and related articles and will continue as normal.

New contributors will be added to both sites. All existing contributors feeds have been copied over. If you are an existing contributor and would like your feed ‘de-restricting’ on the universe site, please send me an email or catch me on IRC. The only restriction is that all articles should be written in English.

If you host your weblog at http://planet.gentoo.org/developers and would like to also participate in the universe site, let me know, and I will give you the ability to add more categories to your blog. (You still need to keep Gentoo stuff categorised separately so that the original Planet can keep running as normal)

I will announce this on the Gentoo mailing lists and create some internal links between the Planet and Universe fairly soon, but please request to be fully included on the universe site right away.

GUADEC was great fun. I wasn’t expecting a holiday to a tropical island, but it could well have been. 35 degrees C over the weekend, as my very sunburnt neck will tell you. A very pleasant city too, with some good biergartens :)

Met loads of interesting people – Stefan from Gentoo, many novell/beagle developers, loads from redhat, plus a few people who I wasn’t expecting to see, such as Kay Sievers.

I’ll definately go next year too, providing it fits in with my exam schedule. Read on for a few photo’s.

Continue reading →

John McCutchan posted a bugfix for the inotify backend of gamin in GNOME Bug 171201. This seems to be behaving better now, but I haven’t been testing long enough to say whether the issues that I discovered really have been fixed or not.

Updated Gentoo ebuilds are available in Gentoo bug 92573. Make sure you read this post if you haven’t been following the situation previously.

Here’s a couple of beagle changes I’ve been working on.

The first adds functionality to index KDE application launchers, and show their icons in Best. The icons fit in quite well, so some eye-candy is required:

Thanks to Diego Pettenò (Flameeyes from Gentoo) for help with locating KDE stuff on disk. The icons don’t seem scaled perfectly, I’ll look into this soon. Also, Best just uses icons from kde’s default theme. If anybody knows how to extract the name of the users chosen icon theme, please let me know.

Next up, I’ve added some tooltips to the Best search results so that more information can be shown. You can’t see the mouse cursor in the example below (import didnt capture it), but it’s quite obvious where it should be.

The tooltips look a bit naff as they are missing the black border you normally get. This is due to Mozilla bug 238052 – fixed in future versions.

In addition to the tooltip above, you can hover over the icon to reveal the mime-type, and you can hover over the “beagle-testing” folder name to see the absolute path of that folder. Other tiles have been modified in different ways, for example, the Blog tile gives you a tooltip showing you the URL you would get to if you clicked on it.

Gamin 0.1.0 was released on Thursday. It’s very similar to the testing snapshot that I produced, but has a couple more fixes on top of that, so its worth upgrading.

inotify 0.23-6 or newer is required. A Gentoo ebuild is available in Gentoo Bug 92573. If you install it, please use the debug use flag, otherwise you’ll be useless when it comes to bug-fixing (see here for debugging procedures).I don’t think it will be included in portage yet, as we don’t currently have any kernels which provide the required inotify version. If you are a gentoo-sources-2.6.11 user, you can find instructions on how to update your inotify version in this post.

A quick check indicates that I can still reproduce the problems I described in GNOME Bug 171201. However, I’m now wondering if some of the problems are GNOME’s fault rather than gamin. This also ties into what some people have said, where the desktop updating breaks easily but nautilus file-browsing works all the time. It appears that the desktop is periodically polling gamin for updates, whereas file-browsing just waits for an event to be signalled. I’m going to investigate this, so if anyone has any idea where the Desktop polling code actually lives, please let me know. I figure that its in nautilus somewhere.

Ok, so a number of people told me about their gamin problems. Some of these, particularly referencing glitches when unplugging USB, seem to be kernel related instead. For now, please use the icon to unmount the USB disk before you unplug. By the way, I run Linux 2.6.12-rc4 and do not experience any glitches even when unplugging during a file transfer. You might want to try it as perhaps “live-unplugging” is safer there.

In a comment, I also mentioned a HAL problem I have: My USB disk only mounts the first time I plugged it in. This is unrelated to gamin, but the Gentopia guys were quick to diagnose it as a HAL 0.4 problem which is solved in HAL 0.5 (present in their overlay). So, if you are experiencing no icon appearing for your USB drive, check with “mount” that it has been mounted. If it hasn’t been mounted, you have the same issue that I do, which is unrelated to gamin.

As for success with the snapshot, well a few people have said it’s been fine, and a few have pointed me to GNOME Bug 171201 where there are some issues described, amongst a lot of confusion of which inotify version to use with which day of gamin CVS. Anyway, I was unfortunate enough to reproduce the issue mentioned there – namely that my desktop and computer:// stopped automatically updating – after restarting the session about 12 times.

You’ll read on the GNOME bug that gamin debug logs are required to diagnose this sort of thing. So, if you were like me and merged the snapshot ebuild without the +debug USE flag, then please merge it again now with the flag set. Then kill gam_server and restart your session.

To debug gamin, you just send it the USR2 signal then it logs to a file at /tmp/gamin_debug_xxxxxxx (it will only do this if you built with USE=”debug”):

# kill -USR2 $(pidof gam_server)

I’m going to be enabling the debug log (as above) when I start each session from this point onwards, but the GNOME bug suggests it may be sufficient to only enable logging once you spot the breakage.

So, please (re)build with the debug flag, and keep an eye out for any breakage. Thanks for the great response so far.

EDIT: Removed links as this is now fixed upstream and in portage

So, many of us enjoy GNOME’s super-efficient integration with inotify via gamin and hal, which allows nautilus to show file updates in real-time, as well as file browsers automatically opening when a CD is inserted, or usb stick is plugged in, etc.

However, the above has been a bit broken for a while. Gentoo Bug 74285 has the details – basically, the media change notification stuff sometimes works once if at all, but then never again in that session.

The fix is a total rewrite of the inotify backend inside gamin. Unfortunately, due to major changes in gamin cvs, this isn’t easy to backport into the latest release (0.0.26). So it looks like using a CVS snapshot of gamin may be in order.

The plan is to test out the CVS snapshot that I have produced, which will then be added to portage when Linux 2.6.12 is released, assuming we don’t find any big bugs in the snapshot.

I’ve produced a gamin snapshot(link removed) from GNOME developer CVS as of right now, with patches from GNOME Bug 303612 and GNOME Bug 303615 applied.

If you are a GNOME+gamin+hal+inotify user, here’s what you can do to help test this:

1. Get the snapshot ebuild from (link removed) and put it in your overlay directory under app-admin
2. emerge the snapshot ebuild:
   

   # emerge --digest =gamin-0.0.26.20050510

3. Patch your kernel with inotify 0.23-7. This will involve first reverting the inotify patch included in gentoo-sources-2.6.11 which can be found here. Note that this is the inotify included with 2.6.11-r7 and 2.6.11-r8. If you are using an older version, now would be a good time to upgrade. You can then patch with inotify 0.23-7 which can be found here:
   

   # cd /usr/src/linux
   ##download the patches
   # patch -p1 -R -i 4800_inotify-0.22-3.patch
   # patch -p1 -i inotify-0.23-rml-2.6.12-rc3-7.patch
   

4. Recompile and reinstall your kernel in the usual way
5. Reboot, start GNOME, and you are done.

To test it, open nautilus on your home directory. Then open a terminal, with both windows visible on screen. In the terminal, create/rename/delete some files, and ensure that nautilus is updated in real-time.
Next, insert a cdrom, and make sure that an icon appears for it on the desktop and the computer:// display is also updated. Use the icon to eject the cdrom, then put it back in again. Check that the icon reappears and computer:// is also updated again. Feel free to do the same with any USB storage you have to hand.

Please leave feedback here – even if it works perfectly! If we get enough testing, we’ll be able to finally solve this.