Friday, November 02, 2007
You're not crazy, the docs really do suck
My friend in LA ran into a showstopping udev-related bug, while installing Ubuntu for a friend. Booting after the initial install, kernel waits for root FS and udev never creates the device name it wants. Device names, it turns out, aren't as persistent as they need to be. His friend installed Windows-2000 and will tell his friends for years to come how half-baked "Linux" (all free software) is. This is how we advocates of software freedom create MS-Windows fans.
I couldn't figure out the bug for him during a short phone call. There's no way he could have figured it out. The reason we were stuck isn't that we're stupid or the bug was at all subtle. It's because Ubuntu doesn't tell us how its boot sequence works, and because udev is poorly documented.
When I had similar trouble with Lilo years ago, I read the 70 page Lilo reference manual (which was pretty good) and I wrote the Lilo Mini-HOWTO. Maybe you've used it. Since then I have been in the same place with a dozen other task problems, but there wasn't any 70 page reference manual or it was incomprehensible or obsolete. (Wi-fi. Docbook. Sound under KDE. SMTP AUTH submission. Postscript fonts in LaTeX. Udev. Postfix restriction classes...) For some of them, I would have written another Mini-HOWTO, but the information just wasn't there to do it with. Source code is not documentation.
I couldn't figure out the bug for him during a short phone call. There's no way he could have figured it out. The reason we were stuck isn't that we're stupid or the bug was at all subtle. It's because Ubuntu doesn't tell us how its boot sequence works, and because udev is poorly documented.
When I had similar trouble with Lilo years ago, I read the 70 page Lilo reference manual (which was pretty good) and I wrote the Lilo Mini-HOWTO. Maybe you've used it. Since then I have been in the same place with a dozen other task problems, but there wasn't any 70 page reference manual or it was incomprehensible or obsolete. (Wi-fi. Docbook. Sound under KDE. SMTP AUTH submission. Postscript fonts in LaTeX. Udev. Postfix restriction classes...) For some of them, I would have written another Mini-HOWTO, but the information just wasn't there to do it with. Source code is not documentation.
