Friday, October 23, 2009

Review - eZ Publish 4: Enterprise Web Sites Step-by-Step

It's been a while since there's been a eZ Publish release from Packt Publishing but the long awaited eZ Publish 4: Enterprise Web Sites Step-by-Step has finally hit the shelves.  Written by Francesco Fullone and Francesco Trucchia it spans 292 pages and details building a site using eZ Publish 4 from server preparation, eZ Publish installation, implementation and deployment. A imaginary magazine site is used to illustrate examples throughout the book.  A number of topics are covered that will help those new to eZ Publish get up and running.

The book is based on eZ publish 4.0.1 and while the current version of eZ publish is 4.2.0 the content is still relevant and there are several notes that refer to features and changes in newer versions.

Packt has provided Chapter 6 - Creating a Design as a free sample download (PDF). A chapter overview is available on the book site as well as a full table of contents.

This is a review of the PDF version of the book provided by Packt Publishing.

Text and structure

eZ Publish 4: Enterprise Web Sites Step-by-Step is not an enjoyable book, in fact I found it quite painful.  The text does not read well and would appear only to have been given the briefest of edits.  Some examples of this are:

 The Achilles' heel of eZ Publish is the template system subframework that cannot, and should not, be overrated, and that is used as a true programming language.
and
When we translate a content object, its main URL will change accordingly. But we should only need to create aliases for a single language. For example, we should create an alias for the contact page in the staff section of the site only for the Italian version.
Unfortunately these are not isolated examples.  I found myself having to re-read passages several times to understand what was being said.

The text overuses words like "moreover" (33 instances), is not consistent in it's use of terminology and formatting.  The authors make use of the "we" as if they are coming on the journey with the reader instead of instructing them.  There is a explanatory "Note" on breadcrumbs that appears twice. I would expected that these types of issues would have been picked up in the editing process.  The problem is that the number and severity of issues distract the reader from the knowledge the authors are tyring to convey.

Some chapters just do not deliver what the chapter titles imply. Chapter 5, titled "Creating an Extension" details how to create an empty extension (directory structure, files). The details of creating the actual content of the extension is found in subsequent chapters. 

The structure of the book is also problematic. At the end of Cchapter 5 the authors take the reader through creating a packaged extension, while at this stage of the book we only have an empty extension.  I don't understand why this information was not moved towards the end of the book.  Another example of this is that the first screenshot of the admin interface login screen appears in Chapter 7, where the first point the user will have come across the screen is in Chapter 3.

The requirements of the magazine site that is being used as an example are peppered throughout the book.  Giving the users a chapter that detailed the requirements, site-map, write frames and mockups up front would better mimic a real world development process help in explaining how this is to be achieved in the chapters where the site is implemented.

Image Quality

The screen shots in the book are not clear and difficult to read. The majority are not annotated with explanation of the image left to the accompanying text.  Images that are annotated only have highlighted regions (circled in red) and are not labeled. 

There are a number of images that are acknowledged in the accompanying text to come from the the "official eZ System documentation" [sic] according to the footer on the page in which they appear, are licenced under the GNU Free Documentation Licence.  The copyright page in the book makes no mention of these images.  I'm not sure if eZ Systems granted permission for their use but I would have expected some official acknowledgement on the copyright page. 

The use of these images (regardless of acknowledgement) is disappointing as the book doesn't present anything new. If the reader has read the official documentation may feel ripped off on recognising them. There aren't many images aside from screen shots in the book and more diagrams would have helped better explain some the the underlying structures that are essential to understand.

Technical Aspects

Technically the book is OK with a couple of places where best practices are not followed.  One example is using a numerical attribute id instead of an attribute identifier string when fetching related objects (the latter is more easily understood and more portable).  Some statements are quite strong (saying that $node.children must be used instead of using a fetch to retrieve the children of the current node) and may be true in some circumstances but would not be considered a rule that must be followed always.

Some interesting concepts of using separate siteaccesses for development, staging and production are raised but I would have liked to see some more detail on the development workflows around these.

The examples used throughout the book rely on command line access to a Unix based system specifically Debian & Red Hat Linux.  If you are not familiar with Unix then you may have trouble following some examples especially if any unexpected errors occur.  I suspect that Windows users would struggle.

The last chapter (12) on Deployment focuses on using the 3rd party eZ Deploy extension.  This seems to be a strange inclusion for this book as I would have expected details of using FTP or rSync naively to be detailed in this chapter. 

The Deployment chapter includes the use of Selenium and PHPUnit for functional testing but doesn't detail testing of the functionality that has been built in the example.  This is where the inclusion of a a "Requirements" chapter could have been used as the basis for quality assurance with example tests being written to demonstrate how specific requirements can be tested with these tools.

Conclusion

In conclusion there is some good technical information in eZ Publish 4: Enterprise Web Sites Step-by-Step but the language and structure make it difficult to follow. New users to eZ Publish may end up more confused than when they started, while as a reference the book isn't ideal as the chapter titles don't always deliver what is expected.

It should be pointed out that the issues with the book do not lie with the authors but with the editors at Packt.  I'm a little baffled that the book was published as it is and would believe if told that I've received a early draft.  I'm not sure that I'd be very pleased if I'd paid for a copy.

3 comments:

  1. Very helpful review, thanks Bruce!

    ReplyDelete
  2. Yep, it's a problem when you have programmers writing books, especially when English is not the native language.

    eZ really needs a copywriter who has a focus on documentation usability.

    ReplyDelete
  3. Hi Geoff

    I agree with you 100% on the cause but this has nothing at all to do with eZ Systems and should have been remedied in the editorial process.

    The book is published by Packt and it is their responsibly to ensure that the end results are acceptable. In fact there are a number of names/roles that are listed in the credits that have let this book down. Many of these have "editor" as part of their title and should have read the book cover to cover and picked up on the most basic of issues.

    Thanks for the feedback

    Cheers
    Bruce

    ReplyDelete