Thursday, June 24, 2010

Guiding Parameters for the Book

The ZODB (Zope Object DataBase) is arguably the most widely deployed Object Oriented Persistence system in the world. Certainly it is the most widely deployed Python-centric persistence mechanism in the world. Every Zope, Plone, and Zenoss installation (well over 3 million downloads) ships with the ZODB. The library is usable by all versions of Python (except the 3.x series) and has been hardened with over a decade of production usage.

This post is an attempt to provide some constraints around the upcoming ZODB book. Specifically to talk about what will be omitted from the book. I believe it is as important to talk about what is out of scope than what will be covered. So here goes:

  • Zope or Plone usage will not be covered. The goal of the ZODB book is to cover the principles and usage of the persistence system in any Python application. Many people use the ZODB in numerous framework contexts: django, repoze, twisted. Talking about the ZODB in the context of an application/framework shifts energy from the primary task, explaining how to use the ZODB and its supporting libraries from a batteries included Python distribution.

  • Private implementation details of the ZODB. I believe there is some sense of what is public / private members of the classes. Although this clarity is not consistent through all of the packages. There are details in packages like ZEO such as the RPC mechanism which are certainly private implementation and will not benefit ZODB consumers from thorough explanation/documentation.

  • Unused features. There are some aspects of the ZODB that exist and "could be used" but these features may not have wide adoption or consistent experiences from the broader community. Examples include persistent modules or persistent weakreferences. As these features become more widely used they will be revisited in subsequent updates of the ZODB book.

While this is not an exhaustive list of what is to be considered out of scope for this book. I hope it sets peoples expectations of the types of things that are not initially considered for inclusion nor believed to be high priority. A complimentary post would discuss how to prioritize the work in the book. What aspects of the library should be given highest priority to focus on documentation.

No comments:

Post a Comment