Writings about open source software, programming, teaching and life in general
For the last two years (or so) it has been my pleasure to serve as the release manager of a package called ZopeSkel. The package, for those of you who've not used it before, provides a suite of templates for generating Zope and Plone projects: buildouts, themes, add-ons and so on. During my time as the release manager, I've pushed out seven releases on the 2.x series, and now two releases on the 3.x series. But something has always been lacking.
Since the package was first checked in to the Plone collective (exactly 6 years ago today), there has never been a manual that provides canonical information about using ZopeSkel, building software with it, or extending it to provide templates that fit your own needs. There are myriad locations on line where one can find documentation that references ZopeSkel: blog posts, tutorials and even manual pages in other references. Most of these, however, contain conflicting or flat-out incorrect information. Many never caught up with the usability improvements that occurred after the 2009 No Fun BBQ Sprint in North Carolina.
Today, that has changed.
I came to the Plone Symposium East here in State College, PA with high hopes for a documentation sprint during the days following the main event. In preparation, I created an empty Sphinx project buildout and set up a repository for it on GitHub. I did a lot of thinking about what I wanted documentation for ZopeSkel to contain, and came up with some decent ideas. Over the last two days, My sprint partners and I have completely torn those ideas apart, and instead built a fantastic, well-edited manual. It has some very useful information on installing and using ZopeSkel, and plenty of room for expanding documentation on how to extend the system.
Wait, what? Why is the manual for ZopeSkel called the Templer Manual?
Well, one of the goals of the No Fun BBQ Sprint was to break up the monolithic, overly specific ZopeSkel package into a set of smaller, affiliated packages, allowing users of the system to download only the parts they actually wanted to use. ZopeSkel is now simply an 'application' built from packages in the templer namespace, the result of the breakup. The Templer Manual provides the canonical documentation on how to use ZopeSkel, but it also provides full documentation on using templer packages. It also contains a nice target for a place to build a full developer's manual to help ease the path to extending templer's built-in packages and adding your own.
I would like to thank my partners in crime, the sprinters who helped me to finish this task and get the manual online and public. Sally Kleinfeldt, a project manager at Jazkarta in Boston, MA was singularly helpful with her eye for detail and clarity. Ian Anderson of AndersonLeeb Inc. provided a fantastic set of getting started instructions for ZopeSkel and built an outline for the developer's manual out of the questions he faced in building a new template to quick-start Django project buildouts using templer.
There is still a long way to go. We have to turn a list of questions from a new templer developer into a useful developer's manual. We have to add a bunch more information to the manual about how templer came to be and where it is going. But this is a great start, and it's out in the public eye, where it can be found.
Speaking of being found, I started this post talking about the plethora of incorrect and out-of-date information about ZopeSkel that is out there to be found. Our sprint kicked off one more process, which is underway but not yet complete. Brandon Gaddie of the University Of Louisville in Louisville, KY is working on compiling a list of all of the locations online where this information can be found. It's not yet complete, but as it is built we will be visiting pages, blog posts and tutorials across the internet. We will edit the pages we can to correct the content and add pointers to this new documentation. For pages we cannot edit, we will leave comments that will hopefully lead end-users to the correct documentation. If we can do neither, I will attempt to contact page owners to see if the information can be corrected. The goal is to correct every piece of incorrect documentation we can find.
You can help with this. If you know of locations where instructions for using ZopeSkel might be found, please point them out. You can leave comments on this post, or send me an email.
Thanks for your attention, and thanks again to all the folks who have worked throughout the years on this project. ZopeSkel is a great tool. I'm happy to be able to help move it forward, one inch at a time.
I started working with Plone in 2006.
At the time, I had been employed by a department at a large university to consolidate their many existing websites into a single, managed website. We started the project by spending a month evaluating available CMS systems. Plone did not start out as the leading candidate, but as the review process wore on, it became clear that it was the right tool for our job. It had built-in support for most of the features we wanted, and promised us the ability to extend it to fill the rest of our needs.
Just as we finished up our review, the Plone Conference in Seattle was announced. It felt like some sort of cosmic validation of our choice. My boss and I signed up for Joel Burton's Plone Boot Camp training, and we were off to the races.
The first six months I spent with Plone were challenging and exciting. I had to write a PAS plugin to integrate Plone's authentication with our campus SSO (pubcookie), find a way to manage users and access in a department with over 800 employees, migrate content from more than a dozen other sites, create a suitable theme, and on and on and on.... The only thing that made it all possible was the hand-holding and training I was able to receive from the Plone community. Joel's bootcamps (I attended several more after that first one), IRC, the mailing lists, and the folks at WebLion all contributed to my growth as a Plone integrator and developer. Without them, I'd have been lost.
These days, it's a bit difficult to remember what it was like at the beginning. Every task seemed impossibly challenging, every defeat was crushing, and even the smallest of victories was a triumph of the human spirit. But it's important to remember, because every day newcomers approach Plone in the same condition I found myself back then. They have no idea where to begin, a list of goals, and a desire to meet them. It is important that they be provided with the same chances I had to learn and grow, so that they can reach their goals and grow into the Plonistas of tomorrow.
This is why I am offering Getting Off the Ground with Plone next month at the Plone Symposium East at Penn State University. I want to help folks who are just getting started learn the ins and outs of Plone in a way that helps them to achieve what they are setting out to do. I know how daunting Plone can seem when you first start working with it. I've been there. But I also know that there are ways to make it simpler, ways to solve common problems without needing to dive down to the level of core code.
In the course, we'll cover the basics of working with content in a Plone site, and of managing a site for others. We'll learn how to personalize a generic Plone site in the easiest and most expeditious way, working through the web. Then we'll learn how to move those personalizations into a real, installable package so you can repeat the process and even write tests to verify that it works.
If you've been working with Plone for a while, and you're looking for more specialized training, there are scads of great training opportunities at PSE this year. I can enthusiastically recommend every one of them. Steve McMahon gives a great class on developing with Dexterity, the content type framework of the future. Chrissy Wainwright's theming course is an excellent introduction to building themes for Plone. Sally Kleinfeldt has forgotten more about agile project management than I will ever know. And if you're in the market for learning more about Python, the language that powers Plone, you will not find a better, more knowledgable instructor than Chris Calloway.
But, if you're new to Plone, this is the course for you. If you've inherited a site built by someone else and you don't know what to do, this is the course for you. If you need a refresher on the basics and how everything fits together, this is the course for you. Sign up today, and let me help you find your legs, the same way I was helped way back when. Everyone deserves a good start.