or, some thoughts on how Plone can make the first couple of steps less confusing. As Plone makes the transition to “more Pythonic,” more Zope 3-style techniques for installation, add-on product development and deployment, we are gaining tremendous power, flexibility and manageability. These are Good Things.
But, this transition is creating some short-term confusion. We have a few ideas about how Plone developers and documenters can communicate more clearly and consistently, in order to help smooth the curve for new Plone users and integrators.
The big insight: a lot of new users’ initial struggles with Plone and add-on products stem from trouble with making sure they’re using the right Python, and getting products installed to the right Python.
Consider the Pythons that the most commonly-used operating systems include:
Ubuntu Gutsy: 2.5 Ubuntu Fiesty: 2.5 Mac OS X 10.4: 2.3.5 Mac OS X 10.5: 2.3.5 Windows: none
Bottom line: none of these widely used operating systems ship with a system Python that can run the current versions of Zope.
Thus, our Unified Installers download, compile and build a version of Python for the use of the Zope instance they go on to create. Some Plone sysadmins will install a secondary system-level Python, then do all their builds and installations against that Python.
So what’s the problem? Mainly, it’s that our documentation doesn’t make any clear assumptions about which of these scenarios obtains, and instead passively assumes that you’re using your main system Python. This is almost never true.
What I think we should do about it:
– Let’s standardize on an assumption about which Python novice users have, and write all our documentation with that assumption. This assumption should correspond to the way our Unified Installer actually behaves.
– Let’s create a page that talks about the different ways that more advanced users could have Python installed, and how the standard instructions might be different. Mainly, I think the key issue to get clear for people is how to control which Python they’re using when they “easy_install” packages, and how to make sure they’re using the right Python for their Zope.
UPDATE: Kevin Teague offers a great simple how-to on this topic. Right on! I’m gonna turn this into a FAQ on Plone.org ASAP!
All of this gets pretty easy if you use a buildout. But right now, buildout is still pretty developer-centric, and I don’t see it as something that average site admins are ready for just yet. (The new, experiment, buildout-based Unified Installer is a huge step forward for making buildout usable by the masses, though! Big cheers for Steve McMahon!)
It should go without saying that I’m pretty vague on the details here. But I feel like I’m at least coming close to putting my finger on something. Whaddya think? How can we smooth this out?
I agree, I’ve just been helping a couple of colleagues start out with Plone 3 (and as a result am trying to write some documentation). One thing I noticed was that they weren’t exactly sure where their Zope instances were, and my assumptions (based on my own installation) were wrong. When you start with Plone 3 its not just where’s my Python but where’s bits of my Plone (in lib/python now). Even buildout is scarey for a windows user – and again all the bits of Plone are not quite where you expected.
Plone 3 is of course brilliant which is why we care so much that the initial learning curve is steeper than it should be.
Things get even wackier on Windows if you’re installing Plone from source into a vanilla install of Zope. Because there’s no such thing as a “system” Python in such cases; what you get is the Python interpreter that comes with that Zope installer. So you then need to go register it, install PIL and all the other dependencies, etc etc.
This is kind of an old-fashioned way of deploying Plone on Windows of course. Maybe there’s not a technical solution so much as an informational one – “The unified installer is the best practice way to install Plone on Windows”, “Here’s how to use your system Python on Windows” or whatever.
FYI, Feisty’s default python is 2.5.
Jon,
I agree with you on this issue. I met some people who ran into problems because they had the wrong version of Python installed. I think creating a page about the different ways of installing Python or “upgrading” it is a good idea.
This is a good point, though unfortunately a difficult one to standardise, unless we insist that people use an installer that builds a particular Python install. A lot of people won’t be using an installer, and many don’t like to build individual Pythons’ on space, speed and filesystem layout grounds.
One option may be to standardise on the use of a single system-wide but Plone-specific Python build (plython?), maybe through virtualenv.
Note that whilst buildout is immensely useful for developers, creating a buildout for “normal” site usage with “paster” is pretty simple – not really harder than using the Unified Installer – see http://plone.org/documentation/tutorial/buildout. I think if we called it a “sandbox installer” or something like that, people wouldn’t be so afraid of it.
Martin-
It’s not so much that we should insist on standardization in the real world, just that we should make a consistent assumption in our documentation and examples.
I set up my development server with Fiesty and spent hours figuring out how to make Python 2.4 the default but once I got through that I was able to use buildout pretty easily with the help of Martin’s book. We do a lot of small sites and I’m starting to get up to speed, starting my 5th plone3 site and pretty happy overall and though I sometimes curse viewlets and such I really wouldn’t want to have to go back to Plone 2.5 even though I’ve still got miles to go to be able to do some things I could do easily in 2.5 and….I think it’s time for bed.
Kudos identifying a really fundamental problem that’s way too easy to overlook once you get acclimated. What might be useful is trying to break the users into personas, or profiles of stereotypical users based on research, and then write to those personas. Then, assumptions such as which python the class of user might have can be standardized, as well as lots of other useful information about the users. For example, you have Azeen (the persona), who is an admin/integrator who is evaluating Plone for her company. She is interested in quick overviews and getting up to speed well, but it’s also important to get her on the path to a sane install and deeper knowledge. Then you have Thomas (the persona), who works with Plone every day as an integrator and need to be able to repeat deployments and maintain a heavily modified environment. If I’m writing for Azeen, I’m going to assume the unified installer (and its python), not and I’m going to write to get her playing more than get her background understanding (beyond what she’ll need to continue learning from the docs). If I’m writing for Thomas, he’s going to have a custom python install and (and maybe even a buildout), and is gong to be much more interested in “Why does that work.” Taking it out a level, for the community, if we all have profiles of Thomas and Azeen, with their backgrounds and motivations, we can share more assumptions. If we make the personas accessible to the public and relate docs to them because they are written for those personas, many users get entry points tailored to their use cases and goals.
This is a good point, though unfortunately a difficult one to standardise, unless we insist that people use an installer that builds a particular Python install. A lot of people won’t be using an installer, and many don’t like to build individual Pythons’ on space, speed and filesystem layout grounds.
[...] great until you need to install an additional Python package for a Plone product. For which of your multiple Python versions will your installer build the package? This question would be frustrating enough even if there [...]