Open Layers 2.10 Beginners Guide

Thanks to Cameron Shorter for putting me in touch with packt publishing so I could review the new Open Layers book. This is a great chance for me to look at Open Layers as it is not something I get to use professionally as I usually live on the other end of the stack.

Summary since you are unlikely to review a full book review:

• Great introduction to Open Layers by Erik Hazzard
• Around $45 on Amazon
• Available from Packt Publishing for a bit cheaper.
• There is a sample chapter available.
• James Fee Review
• Geoweb Guru Review
• Review - How well does the book address these issues:
  • Typesetting: Paper (8/10), PDF(7/10), ePub (5/10)
  • Documentation: (9/10) - this is the one that matters
  • Usability: (7/10)
  • Examples: (8/10)
  • Explanation of the general architecture: (5/10)

Updated: removed rant about documentation for another post.

Reviewing OpenLayers 2.10 Beginners Guide

Here is a recent tweet from Volker Mische of GeoCouch fame: Why people use web mapping libraries other than #openlayers http://t.co/e4V3VDS #wceu

Problems with Open Layers:

• Documentation
• Default Look
• Usability
• Examples are not good
• No explanation of the general architecture

It is indicative that most of the problems above are not technical in nature, but reflect a lack of documentation. Update: Volker has an entire post which covers this list as does crschmidt.

I will use Volker's list to frame this review, how well does this book fill in the gaps mentioned above?

Typesetting

So what is Open Layer 2.10 Beginners Guide like as a book? It is one of the first ebooks i have tried to deal with directly, so the first step is sorting out how to read it in a productive fashion.

End Result, ePub may be the future of publishing, but at least on a Mac the future is out of reach - stick with PDF. To make this setup productive I needed to go grab a second monitor; one for the book and one to work in.

Edit: removed rant about documentation for another post.

Finally I printed out the first section to see how the typesetting comes across in book form.

• Paper (8/10):

  The typesetting offers attractive with a clean and consistent presentation. The Typesetting features a distinctive look with bold wide headings that act like a black hole on the page (especially when reversed). In physical form this has been offset with nice wide white margins for an attractive balanced presentation.

  Code is presented clearly with line numbers so you can refer to a specific line. There is a missed opportunity here as the code does not have any kind of formatting (for example bolding keywords to enhance readability). While this sounds like a small issue it really starts to add up after a while especially when examples mix strings and javascript code.

  Sections are clearly marked, and importantly consistent allowing you to flip through the content and scan for sections such as "Time for action" that identify step by step instructions.

• PDF (7/10):

  I have to guess that the eBook is intended as a supplement to a printed copy. There are a couple of things that let this use down: 1) the large margins detract from the on screen reading experience 2) Unfortunately the line numbers on the code examples are picked up when trying cut and paste into a text editor.

• ePub (5/10):

  I am going to guess that the problems with ePub (on every single reader, and noticed by James Fee) is a quality control issue that the publisher can fix in due time.

Documentation

So does this book address Documentation as a weakness of OpenLayers?

I have two things I expect of a book aimed at beginners:

• Instant, visual, satisfaction

  Basically make me a believer, or at least believe enough to continue reading.

• "basic as a cookbook" instruction.

  step by step showing me what to expect as I go.

Open Layers Documentation

For comparison the Open Layers Documentation is mostly devoted to live examples. The major and probably underrated advantage is that these are a) always current b) easy for developers to maintain. There is also a FAQ which looks to be answering questions about the project (who cares?) and the start of Sphinx driven prose documentation which looks promising.

While the examples may be a good reference they really are not suitable for beginner docs. Lets see how the sphinx docs does:

• Instant, visual, satisfaction? The sphinx docs start out with an Introduction that is perfect in this sense. The very first heading is Creating your First Map

  Total time for visual: 2 mins

  While this may not the best metric for evaluating a book it is at least how I evaluate when in a book store. Can I understand the "hello world", if not I hunt for a simpler alternative.

  Did I understand anything of what went on? Not at all (sigh). Simply adding the empty *script* block so I knew where to cut and paste into would help. Only reasons I was successful at all is because they put the example together at the end.

• Basic as a cookbook? The sphinx docs fall appart here as they assume I know what I am doing (surprise I don't - where does the script block go again?). The steps were not numbered (helpful when all the concepts are new and you cannot tell the paragraphs apart). And surprisingly for open layers there is no visual included on the page showing what the results should look like (really important for a beginners guide as it is so hard to know if you have completed something correctly).

  To be fair these are probably not beginners docs and the intended target audience probably knows more than me about how things work.

So how does OpenLayers 2.10 Beginners Guide fair:

• Instant, visual, satisfaction? (7/10)

  Getting something on screen is covered in the first chapter. While we do have to sit through an introduction and background information, we do finally arrive at "Time for Action" section on downloading open layers followed by "creating my first map".

  Total time for visual: 30 mins!

  As for the long time; I was unable to cut and paste from any of the reader formats (downside to those helpful line numbers).

  The following shows how selection works in the PDF:
  
  And the resulting paste into a text editor:

  map var
  );
  = new OpenLayers.Map('map_element', {}); wms = new OpenLayers.Layer.WMS(
  

  After typing things in managed to produce an empty map! After checking and rechecking for typos; trying in different browsers, I finally clicked on the page which resulted in the map being shown (a ha something is working!).

  A few questions on IRC (thanks crschmidt on IRC) and I was able to sort out my mistake:

          map.addLayer(wms);
          if(!map.getCenter()){
              map.zoomToMaxExtend();
          }
      

  Can you spot it? It should be map.zoomToMapExtent().

  So while I would love to give this one high marks for the clear instruction; it was a frustrating introduction to the book.

• Basic as a cookbook?This is where the book really hits it out of the park.

  As other reviewers have mentioned, the second chapter on firebug really underlines the fact that this is a book aimed at beginners.

  While intellectually I know that firebug is the standard environment for working with Javascript without going crazy; I only know this from watching coworkers. So I am thankful for the kind introduction using a domain I have some familiarity with.

  In terms of the step by step directions I find Mr Hazzard's writing clear, and more importantly on topic. Any explanation is safely separated into a "what just happened" section so it does not get confused with the step by step instructions.

  The other important aspect of step by step instructions is the pictures allowing you to verify progress and have the all important reassurance that you are on track. The pictures are plentiful but not pretty. While I understand that the result needs to be printed in black and white

  I did suffer a little bit of platform and version burn during the initial install instructions; I wished that the instructions were given once each for (linux, windows and mac) as it is hard to follow a mix of linux and windows directories and then be presented a screen snap of some kind of linux file explorer in order to verify you did the steps correctly.

  Once the book gets underway these platform specific issues vanish. There is a small "bait and switch" with the preface indicating that you can use any browser followed by the second chapter being dedicated to firebug.

Still this an excellent example of how to write documentation for beginners, working with Firebug is really assumed knowledge that anyone calling themselves a Javascript programmer (and thus a candiate for working with OpenLayers) is normally expected to bring to the party.

The rest of the book continues in this fashion offering a nice logical introduction to key concepts.

One shock for me coming from a GeoServer background was how much isolation OpenLayers offers from OGC standards. A good example is Style handling with Symbolizers being introduced directly and no reference made to Style Layer Descriptor standard.

Default Look (9/10)

Next up on Volker's list is the default look of OpenLayers. In this case the book goes way beyond what I was expecting from a simple beginners guide. There is an entire chapter devoted to themes covering how to style the controls use by OpenLayers.

I am not sure what the OpenLayers examples are like in this area; but I expect the book will help websites migrate away from the default looks.

Usability (7/10)

Usability is going to be one of the technical issues on Volker's list. This usually comes down to making a web application both simple and direct to work with, and "snappy".

The book does manage to mention performance in a couple of sections; and emphasises the benefit of a fast web mapping application along with specific guidance on TileSets vs WMS. It also goes through the exercise of cutting your open layers file down to just the parts needed for your web mapping application.

So for a beginners guide this book is aware of performance and usability issues and takes some steps to address these matters.

Examples (8/10)

This is an interesting entry on Volker's list - "The examples are not good". Personally I like the examples on the OpenLayers website, but I agree they should not have to bear the entire responsibility for documentation.

The examples in the book are more in the nature of step by step instructions, while I have a terrible time cutting and pasting out of the PDF, they are effective and plentiful.

One thing I would love to see in both the book and the website is the use of the natural earth dataset (or any other attractive dataset). The default blue and white map has come to define what OpenLayers looks like; and while it may be functional for examples I am sure we could come up with something more exciting.

Explanation of the general architecture (5/10)

This is an interesting topic to consider with respect to a Beginners Book. I certainty feel like I know some of the moving parts in an OpenLayers application, but I expect I need to build a few applications to feel comfortable.

With that in mind this book really does span a broad range. Starting off with some object oriented basics in Chapter 1 (for those new to Javascript). A couple of reference sections for the key concepts of Map, Layer, Vector Layers and Style. With a chapter on Making a Web Mapping Application bringing it all together.

So as a reference the book performs admirably. Does it address Volker's question about the general architecture? Probably not. I would of loved a picture of how open layers fits together to give me a better feel for the general architecture. Indeed I almost expected one after being introduced to Object Oriented concepts in Chapter 1.

Recommendation

I am happy to recommend OpenLayers Beginner's Guide, it offers a nice introduction set at the correct pace for beginners in web mapping. The publisher has an opportunity to fix may of the technical difficulties present with the electronic editions of this book.