Programming Woes

In my career as a sysadmin, I have admittedly written less documentation than I perhaps should have. Some of this was because I felt like the people who would be using the programs / scripts I was writing should know enough to not need documentation, but some fraction of it was just outright laziness. I admit that.

When I did write documentation, though, I made damn sure it was accurate. Right now, I’m starting work on a new project using TurboGears2 on RHEL 6, and the upstream TG2 documentation seems quite thorough – but is horribly inaccurate in some rather annoying ways. I am admittedly not using the most recent version, since I wanted to use the version packages with RHEL – but even looking at the documentation for 2.0, it is inaccurate for what is actually available. The first error was in how the upstream docs told me to start a new project – the TG2 documentation for version 2.0 tells me to “paster quickstart” but the actual software (version 2.0.3) makes me run “paster create”. I had to figure this out looking at the error message I got in my shell when I ran “paster quickstart”. I’m not sure whether to blame upstream for bad documentation (quite possible) or Red Hat for dorking around with the package (also quite possible), but the end result in either case is a bad experience and a low opinion (so far) of TurboGears2 on RHEL.

Comments are closed.