Wednesday, May 12, 2010

A Year of Writing Moodle 1.9 Extension Development - Part 2

Part 2: The First Half of Writing
This is the second of a four part series on my experiences writing my first book, Moodle 1.9 Extension Development. The book was co-authored by Mike Churchward. The four parts are detailed below:

  • Part 1: Getting a book deal
  • Part 2: Writing the first half
  • Part 3: Writing the last half
  • Part 4: Post writing production

Chapter 1 Architecture of Moodle -- Writing Fitness
This is when the true realization of how much work this was going to be started to set in. Intellectually, theoretically, I knew it was going to be a lot of work, but this was when reality started to set in. With researching, coding, writing, and work, it was going to be hard to keep with the schedule.  This first chapter felt a bit like that first two weeks on a new fitness program after being a couch potato all winter. I had to develop some writing fitness and fast.

Packt provided a really nice chapter template that let us focus on writing. There was a learning curve during the first few chapters on how to properly mark the styles of sections and format the document, but the template generally made everything look really nice and professional without a lot of effort. I remember my wife commenting on the first chapter printout, "Hey this looks like a real book!"

Mike and I worked on the first chapter together and still managed to miss our scheduled delivery date by about half a week. It was hard work but enjoyable. We ended up double writing a few sections and decided to write individual chapters going forward.

Chapter 2 Blocks -- Smooth Sailing
I started to feel some writing fitness at this point and developed some good habits. The writing started to be a nice stress reliever at the end of the day. I was able to split the writing up into chunks of 30-45 minutes. There was pretty good documentation on how to write blocks and I had lots of good examples. The coding took a lot more time than I expected, but because of working on it a little bit every day, I was able to turn it in ahead of schedule. In hindsight, this was the first sign of just how hard the code samples were going to be. We really wanted a hands on book that would cover original coding projects as a learning tool. We did not just want to copy lines of code from Moodle and give a dry explanation of what they did. This meant a lot of coding and testing on top of writing.

Table of Contents -- A Marketing Tool

This is about the time we received our first editorial feedback. I was pleasantly surprised that the requested changes were pretty easy to accomplish and we had mostly been applying the styles and formatting correctly with the template document. There were also some very specific instructions for taking screenshots and creating figures that we seemed to be doing correctly.

My major take away, which is obvious in hindsight, is the importance of the table of contents in selling a book. A lot of the feedback came on the proper way to name section titles so that they made the table of contents interesting and engaging. As soon as I read this, I immediately thought of how I decide whether to purchase a book. After reading the description, I immediately go through the table of contents. It's common sense, but Packt had down the mechanics of how to make the TOC engaging and they were able to distill it down to 3-4 recommendations.

Chapter 4 Activity Modules -- The Schedule Goes off the Rails
At this point I was feeling really good. I was enjoying the writing and managed to work diligently during Chapter 3 and got ahead of schedule. I even managed to get an early start on Chapter 4. Everything went downhill from there. I ended up with a perfect storm of issues:

1) Creating activity modules is considerably harder than other plugin types and many of the areas I wanted to cover such as course backup and restore did not have a lot of source material.
2) Renovating house for sale. Remote-Learner had opened a Kansas City office about 9 months earlier. I had rented an apartment so we could move to KC to oversee the launch. My lease was coming up for renewal and I had major renovations to complete on my old house before it could be sold. We wanted to buy a new house in KC rather than staying in an apartment for another year, but did not want to have two mortgages.
3) 150 page RFP for work. I was put in charge of putting together a major RFP that ended up being 150 pages in length (a book in its own right).

What followed was 4 months of the most intense work on all three of these fronts. Needless to say, I was very behind schedule by the end of this process. Luckily, Mike was able to keep moving forward with his chapters.

It took about 3 months of development in my spare time to complete activity Foo!, my example activity module for the chapter. Coding and testing truly took a phenomenal number of man hours.

Now, I faced a new challenge. Just printing the source code alone would have been 65 pages and we only had 24 pages allotted for this chapter. Up until this point, I had been able to cover every line of code in the samples as part of the chapter text. It took another painful effort to review the code base and boil it down to a 30 page chapter. I think all in all that this chapter is better and more readable for the effort.

In part 3, I cover writing the second half of the book, including what it's like to write on the beach in Belize.


  1. Very interesting insight into writers' habits :) I admire and envy your ability as you say in being able to "split the writing up into chunks of 30-45 minutes" I have never been able to do that - I am too tired to think or write in the week and end up writing for hours and hours every other Saturday/Sunday (2 week chapter schedules) in an intense focused burst. I also admire how you managed to co-operate on a book as two authors - not sure I could even manage that :) Look forward to the next installment.

  2. Thanks for the comment Mary. It's indeed interesting how different writers have different methods. I really had motivational issues with the thought of writing for 4-8 hours in a block on the weekend, but working for a shorter block of time just didn't seem like as big of a deal to get started.

    Working with a co-author worked out well. On the first chapter we tried to write together and it worked fairly well but we found we overlapped some topics. Strangely even when we wrote on the same "topic" we picked different things to say and most of our mutual work was saved by combining paragraphs. After that we did alternating chapters.

    Luckily Mike and I have a similar enough writing voice that the tone is fairly similar between the various chapters. I after the first three chapters I did work on adjusting my style to match Mike's and of course our copy editors were great in keeping things consistent throughout the book.

    Mary is working on Moodle 2.0 First Look.

    I am curious how difficult it is trying to write and print a book on such a moving target?