ZopeMag.com | tour_article.html

"Writing good documentation is hard. It's much harder than writing code."

Chris McDonough, ZopeMag Interview July 2003

Tour of an Article
Example: Transactions by Example (Part II)
by Samuel Sotillo

Welcome to a behind-the-scenes look at one of our articles which is exclusively available to our subscribers.

In this tour we will explain some elements found in many of our articles, as well as the reasoning behind them.

It is our goal to create great Zope documentation and it is not uncommon for our writers and editors to go through multiple editing cycles until both are satisfied with the final "product".

For this tour we have selected "Transactions by Example (Part II)" written by Samuel Sotillo. It is the second part of a two-part article on Postgres Transactions and how, together with Zope, they can be used to build an online college registration system.

This article includes several features you can find in many of our articles including:

Sidebar - App Server Requirements
Today Application Servers must provide a minimum set of advanced capabilities. These capabilities are essential for providing the level of Quality of Service (QoS) required by e-commerce. Some examples of these advanced capabilities are:
Clustering:	means transparent interconnection of several systems in such a way that they behave like a single system from the end-user’s point of view;
Session-level fail-over:	this term refers to a back-up operation that automatically switches to a stand-by system if the primary one fails or is temporarily shut down. It redirects users from the failure or down system to a backup system that mimics the operation of the primary one transparently—users should never notice what happened;
Connection pooling:	refers to a cache of database connections kept in memory so that any connection can be ... (The sidebar is longer in the actual article)

Sidebars:

When there are a lot of terms to remember, especially new terms, we use sidebars. In the Transactions by Example article we used them to define important Database and Application Server concepts.

Diagrams:

Some concepts are difficult to understand without a diagram. We have included a sample diagram and its explanatory paragraph to give you an idea of how diagrams can be used to clarify complex subjects.

Samuel created this diagram himself. But if a writer needs help creating a diagram or an image to make a point he has the ZopeMag team and our designers at his disposal. Creating good documentation is a collaborative endeavor.

It is our goal to write clear documentation, which is as easy as possible to understand - we don't mean by this that the articles are necessarily easy but that we put considerable effort into making them understandable. Diagrams and sidebars are just two of the tools we use to help our readers understand various Zope subjects.

Code Snippets:

Best of all, our articles come with lots of examples and frequently with code snippets that you can use in your own Zope solutions. (This particular article has 7 code snippets)

We have heard from several of our readers that our articles have helped them quickly solve a problem at work or for one of their customers.

For further reading:

Where we can, we try to point you to further resources available on the Web or in other issues of ZopeMag for a particular subject.

This concludes our tour.

We hope this tour has given you a better idea of what makes ZopeMag unique. To subscribe to ZopeMag click here. If you have questions please see our FAQ. If you have a question that the FAQ doesn't address -- please contact us.

Home Subscribe FAQ Contact Write for us Privacy Policy Weekly News PyZine opensourcexperts.com