Skip to main content.


This is the archive for January 2008

Thursday, January 17, 2008

Lately, we're feeling good. So good that we decided to go distro, and we're submitting packages like crazy.

This brings up another interesting "hellish documentation" topic. You remember I said the worst doc around was Apache? — well, that's still true, but debian packaging nears it.

The problem with Debian docs on packaging (and with other docs you may find around, as i.e. Ubuntu guides), is that they SEEM good. They are so verbose, pointy, rich, that you are leaded to think that they are good docs. But when you get to do things you learn soon that the glue is missing. The basic overall informations on how to do things and why things are done in such ways is nowhere to be found.

Possibly, they seemed obvious to the first ones that invented the system.

I think the very basic point is the "policy" document, which is a very pointy and pitchy document stating what a Debian package should be and what it must be avoided. However, those rules descend from an overall mystic knowledge that remains precluded to the most, until you learn it by osmosis living in the environment formed by other packagers.

From the "policy", a set of learn-by-doing examples are extrapolated by various sources, as I.e. the Ubuntu packaging wiki. They are good, but usually they are partial and fail in explaining everything but the trivial cases. Worst of all, they too fail to explain the reasons behind things, and why tools works the way they do, so it is rather impossible to extend the usage of the tools beyond the mere samples that are shown.

I agree that doing good packaging (and so, good distros) is an arcane art, but even arcane arts have their grimoires. Even an absurd mass of laws as the Italian Civil Code is based on principles that can be read in books and learned before hitting against the wall of the minute details.

Another lesson learned about how *not* to write docs.