HCoder.org

After a couple of (unrelated) recent events, I remembered that some/most people use some desktop “word processor” for writing and maintaining documentation. After years of working with Wikis for virtually all documentation, I have to say that I don’t understand why people still use those dinosaurs. Using a word processor for documentation feels so nineties.

When working in technical teams, I think the advantages of the Wikis are amazing:

1. You know you’re always reading/modifying the latest version. Uploading to a central server or a shared folder, although theoretically possible (and I’m sure some people do), I don’t think it works as well.
2. You can link all content to any other content (and if you keep all your documentation in the same Wiki, you can link to other project documentation or general company/team guidelines or conventions, for example).
3. You can keep bits of documentation that don’t fit in a standalone “document”, like collections of small tips, lists of things to take into account when you do this or that, checklists, configuration/code snippets and examples, journals, etc. And of course link all that to any other part of the documentation, as stated above.
4. You think “globally”, in terms of the content, not in terms of “documents” that are (usually artificially) independent from each other. Also, it’s mentally cheaper to browse through wiki pages than it is to browse word processor documents, so the documentation is more visible and more used.
5. You focus on content, not on formatting or the way things are presented. It’s also easier to keep the same consistent look and feel for all your documentation, if you wanted to change it.
6. As you don’t have “documents”, just “documentation”, people feel free to edit and update it whenever is necessary, instead of feeling the need to ask the “author” of each document.
7. You don’t need any special program that might not be available in all platforms, or at least not interpret the document in exactly the same way. It’s also easier to access it from other computers.
8. Documents don’t get lost or become obsolete because of the format.
9. You usually get revision control for free (revision control that makes it trivial to see the whole change history for the documentation, review which exact changes some person has made in a given moment, etc). And if you’re using a Wiki that doesn’t support version control, you should use a different Wiki ;-)

Of course, I’m not saying Wikis are the perfect solution, let alone independently of the team, company, project and context you’re using them in, but I think in general they are quite superior as technical documentation repository for a software development team.

Today, my good friend “Esberrito” warned me that comments were not working in the blog. I hadn’t realised earlier, but I had them enabled so they should have appeared all the time.

I investigated a bit, and it turns out that there’s some bug (apparently related to saving a post as draft, then publishing) that makes the post have an empty “permalink”. When this happens, the link to the blog post looks exactly like the view of the posts for that particular day (say, http://hcoder.org/2008/11/23/ instead of http://hcoder.org/2008/11/23/why-i-hate-rubygems), so Typo decides that it shouldn’t show the comment form.

The bad news is that many posts are fucked now (although I have fixed some of the most recent ones). The good news is that it’s more or less easy to fix. You just have to connect to a “Rails terminal” with the production configuration (with ./script/console production) and do something like this for each post you want to fix:

>> a = Article.find(:first, :conditions => ["title LIKE ?", "GPG%"])
=> #

>> a.title
=> "GPG confusion" 
>> a.permalink = a.stripped_title
=> "gpg-confusion" 
>> a.save
=> true

Lesson learned: don’t save as draft for now (maybe I should upgrade to 5.1.3, it seems fixed there). Instead, untick the “Online” under “Post settings”, and hit “Publish”. That will assign a default, sane permalink value.

I have always thought that systems should be something integrated. Each “system” has its own conventions, cultural values, etc. and I think you have to respect that. I believe in the Debian way (adapting programs to an integrated system, not just creating a large collection of packages that are identical to the upstream versions), I like to adapt my style of programming to the language (indentation conventions, identifiers, tools for building and testing, etc.), I prefer cross-platform applications that look and feel like each platform they run on, etc.

In the same way, I feel that the mere idea of having a programming-language-dependent packaging system is a broken idea. I know it has advantages, and I know that being specific to the language, some things work better or are more flexible, but I just don’t believe in that idea. Why should I use a different packaging system for certain things just because they’re written in Ruby? Why do I, as a user of those programs/modules, even have to know that there’s some Ruby-specific packaging system, that doesn’t integrate at all with my system’s packaging system, and mixing both leads to a mess?

Not only that, but Rubygems in particular is quite hostile to repackaging into a platform-specific packaging system. A lot of people only provide the gems for their software, which are harder to work with than “normal” tarballs. They also use their own conventions for directories, that break the FHS (for example) and basically only make sense in the context of Rubygems. In that sense, CPAN is much better (although I think using it for application deployment is a very bad idea, but that’s a different matter), because at least it installs everything in sane directories, it doesn’t change Perl in any way, and it’s not a special format, just a repository of easy-to-install, easy-to-work-with, easy-to-hack, easy-to-repackage “distributions”.

Why, oh, why?

I have to say I’m impressed with Opera Mini. It’s a very good product that not only is innovative, but also is damn hard to get working decently in a plethora of ill-designed, ill-implemented, crashing-and-burning-at-any-error, incompatible phones. But somehow these guys bring the Internet to everyone that has a mobile phone that supports Java (a pretty low requirement these days)... and that lives in a country where mobile phone operators don’t charge your ass for connecting to the Internet of course (and then again, Opera Mini heavily compresses the pages so you only download a fraction of the original).

And the experience, taking into account the limited interface, is pretty good. And they add features and improvements in every release (namely, they brought back “skins”, added notes to the list of supported Link data types, and probably other things I haven’t noticed). What else can I say?

The other day I wanted to go and buy some board game. I had gone to BoardGameGeek (awesome website BTW) and had made a list of the games that looked interesting. So I go to the shop, and of course most of them weren’t there… but there was some other game that looked interesting but I hadn’t seen before: Primordial Soup. Having Opera Mini in my phone, I could very easily check the rating and some basic information for that game, which helped me decide if I should buy it. Not only that, but thanks to Link I had the list of games I wanted to buy in my bookmarks (I had added them from my Desktop computer), so I could even compare the ratings for that game and the ones I wanted to buy to start with. How awesome is that?

Go Opera Mini team!

I just remembered something really cool that I had on my previous blog: a small box that shows information that “someone doesn’t want people to read”. It’s part of a brilliant campaign called “Irrepressible info” by Amnesty International. Many of you know that I’m very Amnesty-friendly (“supporter” might be too strong a word, since I’m not really doing much apart from being a member), and I think this campaign is just pure awesomeness.

The idea is very simple: you take texts that have been blocked in some country and allow people to show them in their own websites. It’s a simple but poweful way of showing your rejection for censorship and your support for freedom of expression. As for what you have to do to join the campaign, it couldn’t be simpler. You just have to copy some Javascript code from the instructions page and you’re set.

I have of course added the information box to the sidebar, under the “Irrepressible info” header.

It’s been a couple of years now since I have been a digiKam user. I have been mostly happy with it (actually I don’t even use a lot of its features as my needs are not particularly advanced), but from time to time the Flickr would fail for no reason. Some time ago I needed to upload a lot of pictures and it started failing again, so I looked for some alternatives.

Apart from other apps I knew already and didn’t particularly like, I found dfo (Desktop Flickr Organizer), a GNOME application. It was nice, and it was easy enough to upload pictures to Flickr with it, but it felt weird. What I would like to have is some application to manage my gallery, with some option to upload certain pictures to Flickr. However, this applications is more like a local Flickr mirror with synchronisation options. I don’t want all my pictures in Flickr, even marked as private. I just don’t care, and I don’t want to wait for all synchronisation between the app and Flickr. Moreover, I feel kind of tied to Flickr using that, and I’d rather work in a more “agnostic” environment. So it was cool using it to upload the pictures I had to upload, but I wasn’t really going to keep using it.

At the same time, one friend suggested using Picasa to upload some pictures, so I gave it a try. I had tried it briefly in the past, and I remember that some things were nice, but for some reason it was never my gallery manager of choice. So, trying it again, and even using the synchronisation options for the Picasa web albums, somehow I got the same feeling again: it’s nice, but there’s something undefined that makes me not use it. I have to admit that the interface is really fancy and easy to use, and it works decently well, but I don’t completely like the way the synchronisation works, not to mention that I don’t want to be stuck with only Picasa web albums. Also, I’m not happy with it being proprietary, not available in the Debian repositories, and with that special, anti-integrated interface. Some things work much better than in digiKam (I’m especially thinking fullscreen/slideshow, which sucks pretty badly in it), but I still prefer digiKam overall.

As I wasn’t too happy with the alternatives, I decided to have a look at the problem with digiKam. It turns out that digiKam just uses the so-called Kipi-plugins for picture exporting and other things, and that there was a new version of it that fixed a couple of issues… one of them being a problem with Flickr upload. The package is not available on Debian unstable because we’re currently in freeze (unfortunately, that means that Lenny will ship without a functional Flickr-uploading Kipi plugin). However, I saw that the new package was actually uploaded to experimental, so I decided to give it a try. Not only it works like a charm, but the new version 1.6 reworks the Flickr export plugin completely, and now it’s much nicer. So I’m happy now, back to digiKam with a working Flickr export \o/. To install it yourself, make sure that you have this line in your /etc/apt/sources.list:

deb http://ftp.de.debian.org/debian/ experimental main non-free contrib

Then, update your available package list and install kipi-plugins from experimental, like this:

sudo aptitude update && sudo aptitude -t experimental install kipi-plugins

That should do it.