mike watkins dot ca : Easy Install, Often Isn't

Easy Install, Often Isn't

I'm sure I'm not the only one who suffers from "installation frustration" from time to time. At the outset I want to declare that I'm not complaining about easy_install at all here. In fact, I'm not complaining about anything at all but instead am pointing out what a bad installation experience does to the curious.

My story is cyclical in nature. I don't do any Zope work but do work with ZODB and Durus, a ZODB work alike, and a web app traversal mechanism that is Zope-similar. As a result I'm always inclined to check out major new releases of Zope or Grok or Plone and the ecosystem that surrounds same.

Sadly I've learned to expect frustration and failure in pursuit of my goal to get the new tool of the day installed and have a quick peek at a running demonstration app and examine what's under the covers.

Yet as time passes and the frustration fades, invariably I find myself willing to try again, which brings us to the present. Plone 4 is moving through beta releases and today seemed like a good day to install it and peek under the covers. The official documentation is simple enough, but installation failed and left me with a hankering to cure the problem with rm -rf plone.

Later in the day, inspired by the Jazkarta Blog entry on easy_install Plone, I thought I'd do just that give it another go. No joy there either, and the comments have since sprouted a warning that this should not be done, for well and good legitimate reasons.

But the bottom line remains that a buildout driven install plus official documentation failed to deliver a working instance, so what does one do? Roll out rm -rf plone and move on?

This sort of installation frustration isn't limited to major albeit often beta releases, and certainly isn't limited to Zope or Plone or Grok, although their very long chain of tools can make it daunting for a complete greenhorn to puzzle out a solution quickly. I've had the same experience same thing occur with official tutorials, or too often even basic installation documentation is simply wrong.

Remember, this isn't a complaint. I know how much effort goes into solution development and that many products are built largely or entirely on the back of volunteer labour. I'm merely pointing out that a bad installation experience can turn off someone who might otherwise be a relatively decent candidate to use the product and perhaps one day become part of the contributing community. Those who are on the outside of a product's community haven't yet drunk the koolaid and don't know what fantastic stuff is hidden within the bowels of your package, and they might never know, if the cost of admittance is too steep from the outset.

At the very least make sure the new release can install on a totally new system, or a clean virtualenv, by following only the installation instructions, followed verbatim, in your README or INSTALL files. Don't introduce jargon into these first documentation entry points that outsiders will not know.