Learning about things…

In common, I suppose, with many developers I try to keep track of what’s new and what’s coming up in the technical spheres in which I move. In my case that largely means Python, SQL & Windows although my interests do extend further. I keep a weather eye on things like the Python announce list, the PyPI feed and other sources of updates. When I see something new go past which might be interesting, I might go to its web page, skim the README &c. If it looks interesting or useful enough I might download it and try it out. The same applies to updates to libraries and modules I already use. A new version’s out: have a look to see if it’s offering enough to make it worth upgrading.

But it’s well known that documentation is often the poorest part of the package when it comes to open source software (and it’s not always that much better elsewhere, either). And when it comes to trying to get hold of a whole new module or library, it can be quite daunting knowing where to look, where to start. And for me, that’s where the CHANGELOG comes in. Most open source projects have either a CHANGELOG file or at least access to the change control log entries. Browsing through those can be extremely instructive, both to see what the developers’ (or, more commonly, developer’s) focus has been recently and to give some kind of starting point for investigating the library.

Obviously, if you have a very well-defined goal when you come to a module and / or the documentation’s top-notch then this approach is less useful. But, as a developer myself with my own under-documented modules, I know that I’m more likely to pour useful information into a CHANGELOG entry or a commit message essentially because it’s fresh in my mind and I think conscientiously that I should document it somewhere. Certainly, the source is the ultimate fount of knowledge, but even well-written source doesn’t always illuminate the developer’s intent, while a log entry — especially when coupled with the changeset information — often will.

Oh yes, and the thing which prompted this particular diatribe is that I’ve found the “What’s new in Python…” documents, lovingly written and maintained by Andrew Kuchling, to be fantastic documents. Not just for their stated purpose of indicating what’s coming up in the next release, but also as a bit of a backgrounder to lots and lots of little things in Python which, as a constant Python user since 1.5.2, I still don’t know about or forget. Thanks, Andrew!