Rethinking the format of a software engineering textbook

Why did Dave Patterson and I decide in April 2011 to write a textbook for our “SaaS-flavored” CS169?  Aren’t there a ton of software engineering textbooks out there already?  And aren’t there a ton of practitioner-targeted books for teaching Rails, Agile, Cucumber, etc.?

Among the textbooks, precious few focus on Agile, mostly treating it as a side topic, but we think Agile is a great fit for the classroom—1 or 2 week iterations doing complete “mini-lifecycles” of a part of a software system.  The ones that teach Agile use Java (presumably because so many universities are ), whose viscosity outweighs the “lightweight process” advantage Agile is supposed to confer.  Our view is that learning a new language and tools is worthwhile  if it furthers the educational goal of teaching how to build long-lasting maintainable software with maximum productivity.   (I’m one of the contrarians who is still conflicted about the elimination of the Scheme version of the Abelson & Sussman SICP course, since Scheme is arguably the best language for doing what SICP tries to do.)

Also, despite the fact that the #1 request from our industrial colleagues was “teach students how to work with  legacy code,” most software engineering textbooks we looked at barely mention this topic, with a couple of notable exceptions that focus on using existing open-source software as a teaching vehicle.  (For the record, I think that’s a great idea, but not for our course: while OSS affords opportunities for teaching about legacy and refactoring, it often lives in ecosystems whose testing environments are less than delightful to use, e.g. C or C++ code.)

There’s hundreds of practitioner books on Agile, Rails, RSpec, Cucumber, Git, refactoring in Ruby, design patterns in Ruby & Rails, ad nauseam—and that’s the problem.  We probably perused over 10,000 pages of text in those books in preparing the material for our book.  There is no single narrative that weaves the topics together in a way that makes sense to engineers new to SaaS+Agile+Rails, puts them in the context of software engineering history and best practices, and does it in an amount of text that is realistic for undergrads to consume during a 10-15 week course.

Once we decided to write the book, the next easy decision was to focus on ebooks.  Ebooks aren’t the future of textbooks, they’re the present.  So we knew from day one that we needed an authoring environment that would allow us to derive multiple ebook formats plus a dead-tree version from the same source files.  (I’ll probably release this environment as open source once it’s cleaned up; it’s LaTeX, tex4ht, and a bunch of Ruby scripts.)

But since today’s ebooks are generally inferior versions of their printed counterparts, we came up with a whole list of enhancements for what we thought an ebook could be, inspired in part by Al Gore’s Our Choice ebook for the Apple iPad.  Many (but not all) of the features we want are likely to be present in the upcoming iBooks edition of our textbook.  And as I described in another post, ebooks can be updated frequently and errata corrections pushed out to students practically on-demand, and delivering an ebook to an international student is a lot less daunting than delivering physical books.

Ebook aside, though, it’s worth describing a few of the features that even transfer over to the print version, kind of, because I think we’re learning how books of all formats can be better integrated with online materials.

  • Every code example in the textbook, and many additional ones that are part of the lectures or the homeworks, are up on Pastebin.  So even students who doggedly refuse to learn an editor with syntax highlighting can see what they’re missing, plus Pastebin provides 1-click copy-and-paste so they can try the code themselves.  We created automation to keep the Pastebin links in sync with the URLs that appear in the book and ebook whenever the examples are updated and/or the book is revved.

  • Many book chapters include screencasts to show how to use specific tools.  Anyone can watch these for free on Vimeo(albeit out of context), and we’ll be doing an iBooks version of the book in which the screencasts are embedded right into the ebook.

  • There’s no glossary.  With Wikipedia, who needs one?  Instead, important terms in the book are linked to the corresponding Wikipedia entries.  (In the print book, they appear as URIs in the endnotes of each chapter, but in the Kindle book, the links are live as long as you’re connected to the Internet).

  • At the moment there’s no index.  This may be a hardship if you only own the print version, but the electronic version is searchable.  We anticipate it will be common for print book owners to also own the electronic version (though sadly there’s no way for us to bundle the two purchases, since the print book is created and distributed by the CreateSpace print-on-demand shop and the Kindle ebook is distributed by Amazon, which ironically owns CreateSpace).

  • Separately from term definitions via Wikipedia, the book includes various links to interesting news articles, YouTube videos, and other online materials related to the text.  If you’re reading the ebook on a device like the iPad or Kindle Fire, you can just click on the videos and watch them.  The print book has URIs that you have to type in manually.

So that’s what we’ve been doing and why.  The alpha edition, with some missing chapters, is now available (January 2012) at  By March there will be some minor revisions to it and by Fall we hope to have a beta edition that is content-complete.