Svg Vector Icons : http://www.onlinewebfonts.com/icon

OpenLayers Beginner's Guide

Learn programming, web GIS, and how to use OpenLayers


Role
Author
Tools
Pencil + Paper, OpenOffice
Result
Packt Publishing Best-Seller - three consecutive quarters; thousands of copies sold

OpenLayers Beginner's Guide is a book targeted at novices with the goal to teach not only how to use the web mapping library OpenLayers, but also to teach programming and GIS (Geographic Information System) concepts.

I spent nine months using story telling techniques to craft a learning experience designed to prepare the reader with all the tools necessary to build complex web map applications.

OpenLayer's Beginner's Guide

Books are wonderful teaching tools. Whenever I am learning a new subject, I try to find a well written book about it and dive it. Tutorials and examples are great, but a good book promises to take the reader from Point A to Point B, covering everything in-between. My goal with OpenLayers Beginner's Guide was to guide the reader from novice to competent web map developer. To provide the necessary tools for the journey and encourage a smooth learning process, I made use of story telling techniques.

From Blog Posts to Book

While writing the book took over nine months, years went into thinking about it and preparing it. I had spent time working on a web mapping library before they were commonplace (in 2005 / 2006), but eventually switched over to OpenLayers and frequently used it. In 2009, I wrote a blog post about OpenLayers, which quickly became popular and led to a few more tutorial-styled posts.

In 2010 I began working on the book. My goal was to enable anyone with a passing knowledge of Javascript to be able to develop rich, complex web map applications.

Defining a Target Audience

Before considering anything I might write in the book, I figured out first who I was writing the book was for. The goal of the book was to teach, to solve the problem of "how do I make an OpenLayers based web map or app?" While it might seem that the target audience for a beginner's book is obviously "beginners," it's more nuanced. Every reader comes in with their own experience and set of knowledge. The struggle is to provide a shared foundation, a shared basis of knowledge, which can be built on.

My primary goal was to help GIS developers create web maps. Secondly, I aimed to appeal to programmers who had an interest in web maps. So, to determine how to best reach my target audience, I analyzed the skillsets of colleagues in the GIS world. Many were not experienced programmers, but were highly technical.

Because many potential readers lacked a depth of programming knowledge, this is where I needed to start the shared foundation of knowledge. This shaped what the book was about and how it would be written. I would need to introduce programming concepts, but not go as deep as a computer science degree. However, it was important to provide information on how to debug and solve problems as they arose.

Outlining Process

Before I started any writing, I outlined everything. I took a very top-down approach; I specified every concept the book would cover and how they wove into each other. This was an iterative process that took a little over a month. I started by mapping out OpenLayers specific concepts I wanted to communicate.

OpenLayers Concept Outline

After mapping out the concepts the books would include, as well as how they were related to each other, I then outlined how the OpenLayers concepts would fit in with the programming concepts. This led to creating an outline for the book's overall structure.

Initial Book Outline

The book's structural outline went through many revisions. After getting close to the final version, I then structured the chapters individually.

Individual Chapter Outline

For each chapter, I brainstormed ideas, questions, and problems that needed to be solved. After figuring out what the chapter needed to be about, I then structured the content. Consistency is important when trying to learn something, so each chapter adhered to a general format:

  1. Theory
  2. Example
  3. Explanation
  4. Self Test / Quiz
  5. Final Combined Example

Items 2, 3, and 4 made up the bulk of each chapter, and they repeated a number of times. Example, then explanation, then quiz. Repeat this until we reach the climax of the chapter, which concludes with and example putting together everything we've learned. By keeping this structure consistent, readers were able to form expectations and thus be less distracted by the artifact of the text and more focused on the content. To accomplish this, I used story telling principles.

Using Stories to Teach

All stories, at their core, are about problem solving and how characters in situations react. Even Twilight can be considered a teaching tool. By showing how a character we identify with responds to a given situation, it informs us as to how we might react in a similar scenario.

But what does this have to do with teaching programming or even a specific Javascript library? If stories are about characters solving problems, then it seems obvious to apply universal, cross-cultural story telling structures and techniques to a guide designed to teach. I made use of two such concepts: Hook → Build → Payoff and Kishōtenketsu.

Hook → Build → Payoff

The storytelling technique of Hook → Build → Payoff is a broad and simple, yet powerful, device. It is the basis of all jokes, of all compelling drama, of all well told stories. It is a recursive structure, meaning that inside every hook there may be another another hook build payoff structure, and so on. I tried to be cognizant of this concept while structuring the book.

In the first chapter, the reader creates a minimal, simple, interactive web map with OpenLayers. They may not understand it yet, but by accomplishing it, they make visible progress and have something to play with. The build is the bulk of the book - we then immediately jump into concepts around debugging, then more OpenLayers concepts, then GIS concepts, then put them together. Finally, in the payoff, the final chapter combines everything we've learned to lead the reader through the process of creating complex web map applications.

Inside each chapter, I applied this concept to develop the structure TheoryExample - Explanation - QuizCombined Example. This structure has its own hook build payoff recursive structure in the "build" component. The example is the inner hook, the explanation the inner build, and the quiz the inner payoff.

The payoff must use past information to resolve the hook. Concepts should not introduce something out of nowhere. Readers should be challenged, but they should have all the info required to figure it out. Ideally, like good design, reader should never realize this process is explicitly happening.

Kishōtenketsu

Kishōtenketsu was originally developed as a structure for Chinese poetry and consists of four ideas:

  1. Ki - intro
  2. Sho - development
  3. Ten - twist
  4. Ketsu - conclusion

This concept is also used by game designers in games like Mario, Megaman, and many more. Like the previous technique, this technique can also be applied to itself recursively. By building up concepts, introducing twists, and then putting them together in a way which encourages reader to experiment, we can teach more effectively.

When concepts too advanced are introduced too early, it becomes frustrating. When concepts which become too trivial are never expanded on, it becomes too boring and learners lose interest. I used this concept to help further develop each chapter's structure.

The structure of TheoryExample - Explanation - QuizCombined Example is further refined by Kishōtenketsu. The hook, or theory, is the Ki; the example and explanation are part of the build, but also the shō, the quiz is the ten; and finally the concluding example, or payoff and climax, is the ketsu.

Writing Process - Metaphors

I believe we all learn through analogy, building up concepts which relate to pre-existing concepts. So, it was important to me to use as many metaphors as possible to try to ground readers when discussing programming concepts.

In the first chapter I introduce Object Oriented Programming (OOP). OpenLayers is built with this paradigm, so it was necessary for readers to have a passing understanding of it to de-mystify what was going on.

To communicate what OOP was, I wanted to use more engaging metaphors. Nearly all programmers learn OOP through analogies of bicycles or cars or buildings, but unless you're an architect it's hard to really care and connect to it. Instead, I used Batman, the concept of nouns, and MadLibs to teach it. This process was also wrapped up in the "Hook → Build → Payoff" structure: superheros were the hook, the build included a further explanation of the concept, and the payoff was an interactive MadLibs example.

Metaphors littered the book. Most times when a new concept was introduced, a metaphor grounding the reader followed. By doing so, and using story telling techniques, many readers were able to easily follow along. It mirrored their natural problem solving process.


"What's this concept?" (Hook, Confusion) to
"Ok, here is something I already know." (Build, Grounding) to
"Ah, that familiar thing is like this new thing!" (Payoff, Understanding)

Conclusion

OpenLayers Beginner's Guide was a book aimed at novices, designed to provide all the knowledge required to create a complex web mapping application. The book explained programming concepts, GIS concepts, how to use OpenLayers. To craft a cohesive experience and encourage learning, I used story telling principles.

I am happy with the book's success. For three consecutive quarters it was Packt Publishing's bestseller, and remained in the top five bestselling books for two more quarters.

But, book sales weren't really my measurement for success. I strove to help people learn. I received many dozens of emails from people across the world expressing their gratitude. Even with a single one of these emails I would consider my efforts a success.

Because of its success, many people wanted a follow up for the newer version of OpenLayers. The follow up book, for which I was a co-author, was published in 2015 as OpenLayers Beginner's Guide 3.