I'm Not Normally Lost for Words

This post originally appeared on the Software Carpentry website.

I mentioned last week that I'm trying to put together a lecture on packaging and installation. It's proving harder than I expected: I'm not normally lost for words, but I'm struggling to get these ones to come together. My goal is to help people understand what happens when they install software on a computer, so that they can:

1. diagnose and fix problems when things go wrong;
2. understand why the things that are in packaging tools are there, and how to use them.

After a few false starts, I think the best way to do this will be challenge/response, i.e., trace the evolution of a typical scientific software package from a single Python file shared by email to a mix of Python and C that plays nicely with distutils2. Steps I've identified are:

1. A single-file Python script that I email to my labmates whenever I make changes to it.
2. Adding a version number to that file so that I can keep track of which copy someone has (see the essay on provenance for details).
3. Splitting that file into multiple Python files and putting them in a directory with an __init__.py file to make a package, and distributing the result as a gzip'd tar file (again, by email).

What are the next steps? At some point this lecture will have to explain PATH and PYTHONPATH, what .so and .dll files are, what /etc, .rc files, and the Windows registry are... How do I get there from here? What steps have your projects gone through, and in what order?

Later: just to clarify, challenge/response is a teaching style in which you introduce a simple problem, demonstrate a simple solution, point out a flaw or shortcoming in that solution, show how a slightly more complex solution addresses the flaw, and repeat. It's similar to Lakatos' "proofs and refutations", and I find it a good way to help people understand why complex things are complex.