Alex headshot

AlBlue’s Blog

Macs, Modularity and More

Writing Eclipse 4 Plug-in Development by Example: Beginner's Guide

2013, book, eclipse

I’d like to share my experiences in writing Eclipse 4 Plug-in Development by Example: Beginner’s Guide. If you’ve not read it yet, there are is a sample chapter on the publisher’s page available on the publisher’s page that you can use to get a feel of the book, along with the git repository on GitHub.

The book itself is around 350 pages long, and although there’s plenty of code examples (around 5kloc) in the book itself there’s quite a lot of text as well. So what’s it like writing a book, and would I do it again?

The beginning

The whole operation started around a year ago (summer 2012), when Packt asked if I would write a book on Eclipse 4. They have many books on open source projects, and they reach out to prospective authors (for example, they also reached out to Lars Vogel, and I’m sure others as well). It took me a few months to get to get the necessary legal argeements in place, but once I did I started work in earnest.

It’s always worth reviewing legal documents with a fine tooth comb. The standard agreement had a clause which required me to offer first refusal of any subsequent book written to the publisher, which did not engender trust or good faith. This clause was negotiated out of my contract. Note that IANAL and the standard contract may vary over time, but this was my experience.

The plan

Planning for the book – discussing the contents and approximate page counts – took a few weeks. In the end, I had a draft table of contents:

  • Chapter 1: Creating your first plugin (Pages: 30) Delivery Date: 15.09.2012
  • Chapter 2: Creating Views with SWT (Pages: 30) Delivery Date: 01.10.2012
  • Chapter 3: JFace Viewers (Pages: 40) Delivery Date: 18.10.2012
  • Chapter 4: Actions, Jobs, Progress and Error Handling (Pages: 40) Delivery Date: 10.11.2012
  • Chapter 5: Preferences and mementos (Pages: 20) Delivery Date: 31.11.2012
  • Chapter 6: Working with Resources (Pages: 30) Delivery Date: 15.12.2012
  • Chapter 7: E4 Model and Rich Client Platform application (Pages: 40) Delivery Date: 30.01.2013
  • Chapter 8: Features and Update Sites (Pages: 30) Delivery Date: 16.02.2013
  • Chapter 9: Automated Testing (Pages: 20) Delivery Date: 7.03.2013
  • Chapter 10: Automated Building with Tycho (Pages: 30) Delivery Date: 22.03.2013

My plan was to write roughly 30 pages every couple of weeks, with an elongated period over Christmas (and because the E4 chapter would take the longest and thus the estimate be more variable). In the end, I hit all these dates except for Chapters 9 and 10, in which I slipped by one week. (The final chapter was shipped whilst I was at EclipseCon 2013.)

Having a definitive timetable was an enabler for me to deliver the book. I’m generally very good with deadlines (pay this bill by this date) and not so much at open ended tasks (I should really finish off the archway). But whether it’s your style or not, having deadlines for any task allows you to estimate how long it will be and provide progress reports along the way. In this particular case, it was also planned to time the release of the book alongside Kepler’s release, which added an extra constraint to the schedule.

I’m glad I made (and mostly stuck to) all these deadlines, but it was a lot of work.

The writing

The best way to learn something is to write about it. I’ve written about Scala, Git and the Git Tip of the Week purely as a selfish interest in learning about the various different technologies.

In fact, writing about things was both how I started my first company (International Object Solutions) by developing some Java training back in the days of Java 1.1 and 1.2. This in turn led to me doing a lot of training on Visual Age for Java, and then ultimately the WebSphere Studio suite of products – which is how I got involved in Eclipse in the first place.

Writing about things you already know is (relatively) easy. Admitedly there has to be some kind of plan and structure; typically I start off with top level headings (such as the chapter titles above) and then break them down into sub headings and sub-sub headings. A generic OPML editor will do this, or you can just use markdown or HTML with nested lists.

From a code perspective, being able to build up an exercise by layering more and more functionality is slightly more challenging. It’s not that adding commits is particularly difficult in a Git repository; but (for example) when I discovered I should have used a slightly different data structure later on, I had to go back and fix not only the code that needed it, but go back through piror examples (both in text and in commits) and change the examples appropriately.

The schedule

Most of the writing I do, I do at night. I’m a night-time person, really. I would probably spend 1-3h per night writing (either code or prose) until I had enough to fulfill the next installment, and then take a break.

This probably ended up see-sawing more than I would have liked; I would go through a burn period to deliver a chapter, and then collapse in a heap for a few days afterwards to recover. The progress became more syncopated over time.

I also spent a good chunk of some weekends writing (particularly if a deadline was looming). Throughout a couple of critical sections I ended up writing most of the weekend, with brief breaks to have time to spend with the family. Needless to say at the end of those sprints I had more time to recover afterwards, which didn’t help the subsequent chapter.

The rewrites

Once the first draft of the book was complete (yay!) in March 2013, it was time to address the reviewer comments. I had a great set of reviewers for my book who were able to give very specific feedback; and in the case of Ann Ford, really detailed parts of the code samples which she’d discovered errors in either my transcription or the layout.

I also had a lot of stylistic rewrites to do; the first drafts were very wordy, instead of the bulleted style that fits Packt’s “Beginners Guide” series. Actually, had I had feedback about this nearer the start of the project it would have helped enourmously, as it cost me several weeks of rewriting to put it into the house style after the fact.

The rewrites took me up until early summer, at which point we ended up back-and-forthing over smaller and smaller changes.

The typesetting

The actual draft style for the book was pretty ugly, with orange and green borders for titles. Fortunately the post-production phase (which was handled by several people in parallel) turned it into the more publishworthy style that the book ended up.

This didn’t all go to plan; despite me laying out all class references in Courier New font, the font changes were all lost; and even more frustratingly, many words (like Widget) were decapitalised (widget). Restoring these changes took the bulk of the typesetting review work. I am at least partially to blame for this; apparently some document built-ins had the correct style to use for these things (which I didn’t apply) and I’m grateful for the level of attention given to both the first few attemtps and my ever increasingly nit-picking of the book as it entered the final stages.

The front and back matter

Once all that was complete, it was time for the blurb. You know, the bit at the front where you thank your parents and family for putting up with you, the reviewers for all their hard work, your work colleagues for not commenting on what a zombie I looked like on Monday morning, that kind of thing.

And the back blurb, too.

It’s really, really, difficult to summarise a book in a few bullet points. Yet it’s these bullet points the appear on the front and back coveres, and get put up on the publisher’s site and on places like Amazon. You know, this stuff:

What you will learn from this book

  • How to create plug-ins for Eclipse 3.x and 4.x and automatically test plug-ins with JUnit
  • How to display tree and table information in views
  • What are the specific differences between the Eclipse 3.x model and the Eclipse 4.x model
  • How and when to build user interfaces from SWT and JFace
  • How to run tasks in the background and update the user interface asynchronously
  • How to build plug-ins, features and update sites with Maven Tycho and automate user interface tests with SWTBot
  • How to store and obtain preferences, and how to integrate with the Preferences panel
  • How to work with the Eclipse resources model for creating and updating files and reporting errors to the user

I found these summary bullets more difficult to write than the book itself. How do you summarise everything? How do you put it together? What, in a nutshell, is the book about?

The aftermath

I had always wanted to write a book, and this opportunity was too good to pass up. So now that I’ve done it, what next?

Well, writing a book is hard work. Really hard work. It took a lot of persistence, effort, time and patience from my friends and family. Now that I’ve actually written a book, I’ve got it ‘out of my system’ and so don’t feel that I need to write more; at least, for now.

It also took a toll on my twitter stream and blog posts, as you may have noticed.

AlBlue's Blog Post Count By Year: 2004 (18), 2005 (43), 2006 (116), 2007 (101), 2008 (47), 2009 (75), 2010 (69), 2011 (102), 2012 (24), 2013 (11)

So, would I write another book? Well, it’s a significant commitment of time, and there’s no guarantee that the book is going to do well. But whilst I wrote the book with the intent it will be useful by others, I also wrote it for my benefit as well. In fact, I don’t think anyone really writes a technical book to be famous or rich; and whilst I hope it does well, the Amazon UK sales ranking of 155,433 is probably as high as it will reach.

Never the less, I hope if you have bought the book you found it useful, and if you’re thinking of writing a book this will give you an opportunity to see behind the scenes as to what happens.