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.
The new docs are now publicly available on Read The Docs as the Templer Manual.
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.