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 Theory → Example - Explanation - Quiz → Combined 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 Theory → Example - Explanation - Quiz → Combined 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.