Elements of Training Book Style

One thing my recent adventure in learning Android has me thinking about is books for teaching new technologies. I’ve been doing what I do now for over 20 years, so I’ve had to learn many new technologies. Often, I have to learn them fairly rapidly, but I also need some depth while I am learning. I have also trained people on several technologies (some of my own making, some built by others), and one product I worked on included a reference and training manual that I co-authored. Based on my experience in this, I have some suggestions for any future authors of books teaching new technologies. I’ll use mobile applications as an example, but hopefully people can read between the lines.

A caveat here is that these approaches may not work for everyone. However, in my experience, they work for a very, very broad segment of the population.

General Elements

Lighten Up On The Introduction

Some books have a fairly short, almost perfunctory, introduction to the topic. Others I’ve seen (and the Android books I looked at recently are bad for this), have a long-winded introduction that includes a substantial amount of text trying to convince you that the technology in question is a good idea for you to learn. I have a hint here: the reader already has the book. They’ve already decided the need to learn the topic at hand, so stop trying to sell it to them. A short, simple introduction that gives a bit of the history of the technology and how it got where it is today will suffice. The point isn’t to sell the platform, the point is to educate the reader on “the story so far” in a concise way.

Repetition of Common Tasks

One aspect of training a person, whether it is knew information or a new physical activity, is that repetition helps with retention. There is a reason sports coaches make athletes perform what appears to be a mundane task over and over again: it trains the appropriate parts of the person to do what needs to be done. The same can also work for learning new technologies and the tools that support them. So how does this work? Again, using developing mobile applications as an example, a book should have the reader create new apps/projects many times over the course of the book. Yes, it may look tedious, but it helps the reader get used to using the tools, particularly an aspect that they won’t use as often as, say, creating new screen layouts or classes. This is also particularly useful for platforms (like iOS) where you have multiple types of projects available, since the reader can get some experience creating a few of the basic types.

Explain the Tools

Part of building apps for any platform includes using the tools to do the job. Over the course of the book, the content should not just explain the topic at hand (for example, how to use a push button), but also illustrate how to use the tools available while you work. This includes things like project/app creation, creating classes and other files, creating the user interface itself, and how to debug the app.

For platforms where this is a choice of tools, like for Android: pick a toolset. So, if Eclipse is the more common platform to use, then include a description (and screenshots) showing how to use Eclipse to basic activities.

Also include, again as part of the rest of the activities, how to use things like any emulators or simulators, since the user will spend a fair bit of time in these when they are building their own apps.

The last and crucial item to include is how to get the app running on an actual device. Some kind of walkthough of how you get any certificates, sign the app, etc. makes it more satisfying for the reader. It is one thing to see your app in an emulator. It is another to see it actually running on a device. I still get a kick out of seeing a new app I’ve built running on an iPad or a Galaxy S, because it makes it more real. My first foray into getting an app working on an iPod Touch was a bit frustrating, because the book I had didn’t explain it, and Apple’s documentation is okay but not great on that topic.

Include the Code and Explain It

Every section should include the code as part of the text, as well as a complete and separate download. I have seen authors comment that the book would get too big, and to this, I say I don’t believe you. Two recent examples of books that include all the code you work with in the book are Aaron Hillegass’s excellent Cocoa Programming for Mac OS X and Mark and LaMarche’s Beginning iPhone 3 Development: Exploring the iPhone SDK. I have used other books years ago for learning Visual C++ and MFC, Visual Basic, and J2EE technologies that took similar approaches: all of them include the complete source code, built up step by step over a chapter, with the text annotating the code as you add it. None of them were physically gigantic books, and they covered a surprising amount of detail.

When annotating the code, what is key is that the text not just say what you are supposed to do, but explain why you do it. Part of using code examples isn’t to just explain the mechanical aspects of buttons or web interaction or network programming. Part of the code samples and the annotations that accompany it are to explain the general approach, patterns and philosophies behind the underlying system and architecture. The code will make that architecture and those patterns “come alive” in that they illustrate how the system does what it does. The code and its description should also highlight recommended or best practices for the platform at hand.

One final point on sample code: make sure it works on the platform you have targeted. It is very frustrating to spend a portion of your day dutifully typing in the code, reading what is being done, and then finding the thing won’t even compile because a variable name changed partway through the exercise. I have seen a few books where the code is flat-out wrong: if you entered it as-is, it would not compile, let alone run.

Basic Structure

Again, I’ll use mobile app development as the context for a book. The details will obviously vary for other topics.

Any instruction book should really be broken into 2 main sections: the first to cover the basics and topics that will be common to almost all mobile apps, and the second to cover more advanced topics.

Section 1: The Basics

This section needs to cover the basics, those elements that will likely be common to almost all apps on the platform. Key topics for this section need to include (possibly not in this precise order):

  • Start with a simple app to illustrate the structure of the app
  • Discuss user interface layout and design, and how it works on the platform
  • Examples and a description of all basic interactive UI controls like buttons, checkboxes and radio buttons
  • Cover static elements such as images and text labels
  • Talk about more advanced components like single-line and multi-line text entry fields, lists, toolbars, drop-down/pull-down menus and pop-up menus
  • There needs to be coverage of the container/view hierarchy and how to work with it
  • Discussion about advanced containers like tab bars or tab views
  • Make sure to cover transitioning between views, as well as any platform-specific navigation features like the iOS navigation bars
  • There has to be a section on device rotation, because that will occur quite often while an app is in use
  • Be sure to talk about things like how to hide the keyboard when it isn’t needed
  • Have a chapter covering dialogs and user alerts, and how to let the user know about significant events, errors, etc
  • Talk about persistence to the device
  • Cover managing preferences and settings
  • Include a discussion about the application lifecycle, and anything special that is part of multitasking
  • As a final step, show how to get the app running on an actual phone or tablet

Based on what I’ve seen in both iOS and Android, this covers a major portion of what most apps will have to do or use. This should be enough for someone to build a simple app and then be able to get it on the appropriate app store.

Section 2: Advanced Topics

The advanced topics section is where you can cover things like

  • location services
  • network and wireless programming
  • web services
  • cameras and image capture
  • audio capture and playback
  • 2D/3D animation
  • access to shared local data such as address books and calendars
  • accessing attached devices and accessories
  • creating custom controls, or customizing controls built-in to the system

This is for people who are building more sophisticated apps, or who need more complex features. However, a beginner doesn’t need these just yet, and for some, they may not get to these parts for a long time. Including them, though, allows some of the more ambitious readers to learn a lot about some the cool parts of the platform.

An important note here on web services: please pick a Internet-based service that doesn’t require any kind of sign-up or developer key. One book I worked through (Hillegass’s book) tried to use an Amazon API as an example. The problem, though, was that the Amazon API had changed since the book was written (so the one in the book didn’t work), and it required sign-up and specific developer keys. A better example comes from Reto Meier’s Professional Android 3 Application Development. In it, he uses the US Geological Service’s earthquake data to illustrate how to get at data on the web. The API is simple, and doesn’t require any sort of sign-up or developer keys.

Are There Perfect Books Out There?

I won’t say that I have ever found the “perfect” book for learning new technologies. I will say that I have found good ones that I’ve already described and discussed here. I would also caution any author about trying to go “too deep” and cover every possible topic on a platform. There comes a time where a specialized book on things like game development, advanced security and such are better than trying to overload a book that should get someone started on the platform.

I will also reiterate that this approach to a training book won’t necessarily work for everyone. Some people simply want to see sample code, and will work their way through the tools on their own. Some want to have some detailed descriptions on how some features or elements of a system work. However, as I said, after having spent the last couple of decades both as a student and an occasional teacher, the approach of having someone work through code samples (including having them type it in as they go) seems to work well for many people.

Advertisements

One thought on “Elements of Training Book Style

Comments are closed.