Thursday, May 27, 2010

A Year of Writing Moodle 1.9 Extension Development - Part 4

Part 4: Post Writing Production
This is the final 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

I lied to myself and I knew I was doing it while I was doing it. I told myself, "if I can just finish the writing, the time commitment will go down and my life will become somewhat normal again." I had a suspicion that this wasn't the case, but it did help me get through that last push during the holidays. I think in fact that I ended up spending more time per week in editing and reviewing than during the writing. Part of this is probably due to the fact that I ended up writing some new sections from the feedback during editing. I could have said no to this, but I really wanted to have a quality book when we were done.

Technical and editorial review
We sometimes received notes just from Packt editors and sometimes we received a combined set of notes from both the editors and our technical reviewers. We got many requests to clarify small sections of text, to add new sections, and for more screen shots. An interesting note on the publishing process, while the author knows a bit of the economics of the book in terms of target page counts, etc., technical reviewers are just given a book description and the chapters. This gives a very different perspective and made it really clear that 250+ pages covers the core concepts, but that we could easily write 500 pages to make a comprehensive work on Moodle development.

Kudos to Anthony Burrow for doing such a great job with the technical review. I don't think I know a nicer, more generous person than Anthony. Anthony you are a kind soul!

Most chapters ended up with 2-3 drafts before being submitted for copy editing. Some of the early chapters had as many as 5 or 6 drafts. Packt has a very specific naming convention for drafts that helped keep track.

This process took about 2 months.

Too many pages!
Midway through the process our editor noticed that every chapter we submitted was growing in size from the original draft. We had quickly burnt through an extra 25 approved pages and needed to cut 6 pages. On top of this, I still had requests from an unedited chapter to add at least one major new section and more screen shots. It was decided the only solution was to cut the last chapter from the print version of the book and make it available for free download. This was a confusing time, but eventually we got through it and ended up with a better book as a result. Packt encouraged us to add anything we needed for the book to be really great. In fact, at the last minute before publication, our editor was able to get approval for the extra pages to include the final chapter in the printed book.

Code Review / Copy Edit
The final stage of production was copy editing and code review. We worked with a couple of great guys named Chris and Hitesh.  They were equally conversant with chasing dangling participles as they were at parsing PHP code! What a cool and unusual combination of skills. This team performed fixes to word usage, punctuation, code formatting, and installed every bit of code from the book and tested it. I actually received back some notes like "we had to edit line X of the sample to get our test environment to match your screen shot." I was simply blown away.

This part of the process went pretty quickly, typically 45 minutes to an hour per chapter. The exception was one code sample I decided needed to be re-written to fix an issue with the user interface. Major thanks to this editorial team. They really made us look good.

It's Done!
It's been a long and challenging year, but a growing year. I would recommend to anyone who, like myself, always wanted to write a book, to take the opportunity if presented. Or even better, decide today to make your own opportunity.

    Monday, May 17, 2010

    A Year of Writing Moodle 1.9 Extension Development - Part 3

    Part 3: The Last Half of Writing
    This is the third 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 8 Reports -- Writing in Belize
    Our CEO, Bryan Williams, is an avid SCUBA diver. For many years, we had talked about going on a dive together with my wife Michelle. Last September, we decided to finally make this happen and to get some much needed sun. So after looking at the options, we decided on a trip to Belize. I worked out that with Mike's efforts on Chapters 5-7, that I could get back on schedule, if I could complete a full chapter while on vacation. I must say that writing on the beach is really the way to go. While it can be a bit tricky getting your computer screen at just the right angle to be visible, its well worth the effort. I didn't quite manage to get the entire chapter done on vacation, but I got most of the source code finished and completed all but one section on the plane ride back to the US.

    Feeling good about the progress and rejuvenated by our trip, I quickly wrapped up Chapter 8, on my return to the states.

    Chapter 9 Integrating with 3rd Party Systems -- Drive Crash!

    I was really feeling good again at this point. System integrations are a particular specialty of mine and I had an existing library of material that I was pretty quickly able to work into half of a completed chapter. I put in some extra time during the evenings and had most of the coding samples quickly completed. Then ene night, as I was packing up, I notice that my laptop which should have been fully charged was showing a low battery. When I get home, the computer wouldn't boot. The battery had died and somehow this caused a nearly complete wipe of my SSD drive. While I had backups, I had done so much work in a short period of time that I didn't really have a good backup of the materials for Chapter 9. Even more disruptive was taking the time to rebuild and reload the computer and restore my files. I went from finally being caught up with the schedule to being 2-3 weeks behind. My take away from this was, you can always improve your backup system, even after 15 years working in IT.

    I managed to rewrite everything and get it out the door. I think I rushed it a bit trying to get back on schedule; this chapter ended up being one of the ones I spent the most time editing later.

    Chapter 12 Pagelib -- Back on Track
    Thankfully, our CEO has been very supportive of the book effort. He agreed to give me half a day per week during work hours to work on the book. This got me back on track to deliver the book on schedule. Chapter 13 was remarkable in that it was probably the only chapter in the book that we didn't end up tight on space. While pagelib is a core library, it is pretty simple. Mike and I actually recommended this as most easily cut from the book, when we thought we were going to have to delete a chapter. Luckily, we were eventually able to get the entire book into the print edition.

    Chapter 14 Web Services-- Writing on Christmas Break

    It was getting down to the wire. I was confident that there was enough time to get all the writing finished. Especially, since we had a block of time off for Christmas and later for New Years Eve. We had a major snow storm hit during this break and I recall not leaving the house for about 4 days and a final marathon coding/writing session finishing at 2 AM. I managed to submit the last chapter 2 days before our final deadline for the book. I can't tell you how much of a relief it was to finally hit send on that last chapter, especially considering how far behind I was just a few chapters into he book.

    In the next and final part, I talk about the production process.

    Friday, May 14, 2010

    Interview with Packt

    I recently did an interview with the staff at Packt Publishing, the publisher of Moodle 1.9 Extension Development.

    Packt: Your book is published now. How is the feeling of being a published author?
    Jonathan: I don't think it has totally sunk in yet. I feel a tremendous sense of accomplishment. I have wanted to be a writer since I was twelve years old. Mike and I worked tremendously hard over the past year to put the book together. It was especially difficult putting together all the coding examples. Once the coding was finished for a chapter the writing was relatively easy. I feel really good that while it was a difficult process, that I was able to accomplish our goal of writing a great book on how to customize Moodle via its extensible plug-in model.
    Packt: What benefits did writing a book bring to your specialist area?
    Jonathan: The most direct thing that comes to mind is how much I learned over the course of researching and example creation for the book. Its very much like the saying that you have to teach it to truly learn a subject. I think writing a book on a subject, brings that idea to an even higher level. Longer term this is one more indication of the level of both my personal expertise as well as that of our company Remote-Learner provides in the Moodle space.

    See the rest of the interview at

    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.

    Thursday, May 6, 2010

    How to Create and Modify Moodle Filters

    by Jonathan Moore Michael Churchward | May 2010 | Moodle
    In this article by Jonathan Moore and Michael Churchward, authors of Moodle 1.9 Extension Development, we will discuss the basic concepts of creating a Moodle filter, which includes:
    • How a filter works
    • Using the API to create filter code
    • How to use language files
    • How to create configuration settings
    Moodle filters modify content from the database as it is output to the screen, thus adding function to the display. An example of this is the multimedia filter, which can detect references to video and audio files, and can replace them with a "mini-player" embedded in the content.

    How a filter works

    Before trying to build a filter, it would help to understand how it works. To begin with, any text written to the screen in Moodle should be processed through the format_text function. The purpose of this function is to process the text, such that it is always safe to be displayed. This means making sure there are no security issues and that any HTML used contains only allowed tags.
    Additionally, the output is run through the filter_text function, and this is the function we are interested in. This function takes the text destined for the screen, and applies all enabled filters to it. The resulting text will be the result of all of these filters.
    filter_text applies each enabled filter to the text in the order defined in the filter configuration screen (shown in the following screenshot). The order is important; each filter will be fed the output of the previous filter's text. So it is always possible that one filter may change the text in a way that impacts the next filter.

    Tuesday, May 4, 2010

    A Year of Writing Moodle 1.9 Extension Development - Part 1

    Part 1: Getting a Book Deal
    This is the first 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

    I can remember wanting to write a book since I was twelve years old, just shortly after discovering Tolkien. So when the opportunity came to write a book in an area where I had some expertise, I felt I had to take it, regardless of whether it made sense with my schedule. I first worked with Packt Publishing ( on the second edition of William Rice's Moodle book. I served as a reviewer for some of the more technical sections. Early in 2009, Packt contacted us to see if we might be interested in writing a book on Moodle development.

    Is this the Right Book?
    I think I could have written a book on Moodle Administration in my sleep, but that wasn't the book we were offered (in fact that book had already been written). You often have to stretch outside your comfort zone in this life to get what you want.  I had a lot of development experience and I had a lot of Moodle experience. But I really didn't have a lot of Moodle coding experience. I had primarily worked at Remote-Learner ( to create our hosting and support groups and later as a project manager for development projects. I had a very good grasp of what Moodle could do out of the box, the overall methods for customizing, and what did and did not require changing core Moodle to accomplish. However, I did not have a lot of on the ground coding experience inside of Moodle. Thankfully, my writing partner, Mike Churchward had this in spades. Long story short, Mike Churchward and I had both wanted to write a book since we were kids and we agreed to enter discussions with Packt.

    Writing a Book Outline and Schedule
    It ended up being a very long 3 month process working out the details of what would go into the book, how long the book would be, and what schedule it would be written under. Packt provided a very detailed guide to writing a book outline along with samples. We had a pretty good idea of what topics we wanted to include from many years of doing custom development for Moodle. Our biggest challenge was figuring out how many pages each chapter should take and a realistic schedule for completing the writing. Mike and I were both juggling very tight time commitments with a growing Remote-Learner. These may seem like minor details to be stuck on for months on end, but writing a technical book is ultimately a business and the economics of the book are tightly tied to its size and delivery date.

    We were really stuck for a while. Packt helped us out with a few guidelines. They had in mind a book no larger than 250 pages of content and that most writers can complete 8 pages per week. I went to a few other books on Moodle from my bookshelf and reviewed chapter sizes for some common topics. As a result we came up with two chapter sizes: 16 page chapters for simpler topics and 24 page chapters for more complex topics. From here the outline came together pretty quickly. We padded the schedule just a bit for some extra cushion just in case work got too crazy -- and it did. If you ever find yourself in this situation here is my advice. Try to get your outline done quickly so you have more time to actually write!

    In the next article in this series, I will cover writing the first chapters of the book.