How 5 people with 4 day jobs in 3 time zones enjoyed 2 years writing 1 book
2 likes824 views
This document recounts the collaborative experience of five authors working across three time zones to write a book about JRuby over two years. It discusses the challenges faced in project management, the evolution of their tools, the importance of establishing workflow and rhythm, and personal reflections on teamwork. The resulting book, 'Using JRuby', highlights practices and lessons applicable to remote collaboration and software projects.
![October 2008
Ola: It seems that the book will take a long time to get
finished..., and I really want to get going....
Ian: It's just been difficult [for the team] to justify
writing about JRuby when they could either be hacking
JRuby or helping someone.... On the other hand, a
phone call gives us a solid block of time with each
other, where we have (nearly) 100% of one another's
attention.
Four months in, and even the five authors are getting antsy—but we don’t know what to do about it
yet. We have, however, discovered that voice chat is much less distraction-prone than text chat.](https://image.slidesharecdn.com/how5authors-slides-110623153137-phpapp01/85/How-5-people-with-4-day-jobs-in-3-time-zones-enjoyed-2-years-writing-1-book-34-320.jpg)
![February 2009
Jackie: Is [Ola’s testing chapter] ready for me to
review? .... This looks really good!
Not much progress expected or seen during the Thanksgiving/Christmas time period. And then, in
late January: a wiggle of hope!](https://image.slidesharecdn.com/how5authors-slides-110623153137-phpapp01/85/How-5-people-with-4-day-jobs-in-3-time-zones-enjoyed-2-years-writing-1-book-35-320.jpg)
How 5 people with 4 day jobs in 3 time zones enjoyed 2 years writing 1 book
- 1. How 5 people with 4 day jobs in 3 time zones enjoyed 2 years writing 1 book Ian Dees Open Source Bridge 2011 This is the story of a big collaborative writing project. I’m telling it for therapeutic reasons—but if you’re a freelancer, a project manager, a telecommuter, or a member of a remote team, you may find the arc of this project familiar. Perhaps some of the tools and techniques we used along the way will be helpful to you as well.
- 2. 5 authors Ian Nick Charlie Ola Tom sketches by Lukas Ketner The five authors are: Charles Nutter and Tom Enebo, the two JRuby project leads; Nick Sieger and Ola Bini, the other two members of the JRuby core team; and me (Ian Dees), a happy JRuby user and the only non-core team member in the group.
- 3. 4 day jobs 1. Sun (Charlie, Nick, Tom) 2. Engine Yard (Charlie, Nick, Tom) 3. ThoughtWorks (Ola) 4. Tektronix (Ian) Collectively, we’ve worked at these four companies...
- 4. 3 time zones 1. Pacific (Ian) 2. Central (Charlie, Nick, Tom) 3. Central European (Ola) ...in these three places.
- 5. 2 years June 2008 - 2010 We started in June of ’08 and finished writing in August of ’10.
- 6. 1 book The book is Using JRuby, the definitive guide to the Java-based Ruby implementation.
- 7. IT’S NOT A BOOK IT’S A SOFTWARE PROJECT Since this is such a code-heavy book, I should have realized much earlier on that it’s as much a software project as a book. We could have used practices that have helped software teams, such as working in iterations and having frequent standup meetings. (Later on, we figured this out.)
- 8. the startup curve http://adam.heroku.com/past/2008/4/23/the_startup_curve Before I tell you our story, let me show you this famous graph drawn by Paul Graham and Trevor Blackwell at the Y Combinator headquarters.
- 9. the startup curve The Process Upside of Buyer Acquisition Wearing Off of Liquidity TechCrunch of Novelty of Initiation Wiggles of False Hope The Promised Trough of Land! Sorrow Releases Crash of of Improvement Ineptitude Here’s a cleaned-up version. It’s meant to represent the ebb and flow of web traffic at a startup.
- 10. the book curve The Process Release! Conservation Harshness of Momentum Euphoria of Reality of Kickoff Wiggles of False Hope Establishment Trough of of Rhythm Sorrow Nagging of Stakeholders Abandonment? It also fits the ebb and flow of morale during the writing of our book. This curve should feel familiar to anyone who’s worked on a multi-year, multi-person effort.
- 11. euphoria of kickoff Harshness Euphoria of Reality of Kickoff Let’s talk about how it all began.
- 12. dramatis personae First, a word about my co-conspirators.
- 13. Ola The Prospector TECHNOLOGY SURVEYS, (RE-)STARTING PROGRESS Ola is like a prospector. You can turn him loose in Testing Canyon, and he’ll suddenly turn up a couple of weeks later with a twelve-pound chunk of gold, saying, “Smelt that, baby.” Someone this good at working without a map is crucial for getting projects unstuck.
- 14. Tom The Analyst BREAKING DOWN HUGE QUESTIONS Tom has an analyst’s mindset. He likes to consider every angle of a subject, write some code, study some more, and then weave a compelling narrative. He doesn’t flinch at huge topics that would overwhelm most people, such as “Tell me everything about user interfaces in JRuby.”
- 15. Charlie The Professor BUILDING GREAT DEMONSTRATIONS Charlie has a library of examples available to fit every occasion. His writing style is very demonstrative: “In this example, you will encounter problem X. To solve it, use technique Y. For instance: ....” He also has a good sense of what things we should explain in the book, and what things we should just fix in JRuby itself.
- 16. Nick The Conversationalist KEEPING THE READER ENGAGED, FINDING GAPS IN FLOW Nick is a natural conversationalist. He connects material to previous ideas, then challenges the reader to absorb the new information. Someone like this is crucial for finding gaps in flow.
- 17. Ian The Yak Shaver THE THOUSAND LITTLE THINGS THAT NEED DOING And finally, there’s the yak shaver—the guy who sets out to write a chapter, creates some code examples to talk about, and eventually falls down a rabbit hole poring through the JRuby implementation. There’s even a place in most projects for a scatterbrain like this: taking care of the thousand little things like maintaining tools, talking to the editor, and so on.
- 18. the old plan I. Introduction V. Working With Data 1. Introduction 8. JDBC II. JRuby and Java 9. XML 2. Ruby 101 10. Web Services/SOAP 3. Java from Ruby V. Rails 4. Ruby from Java 11. Overview/Tutorial III. Environment 12. JDBC 5. Standard Libraries/YAML 13. Deploying 6. Configuring/Running VI. Testing 7. Inside JRuby 14. JUnit/Test::Unit/Mocking a. Architecture 15. RSpec b. Interpreter 16. Benchmarking/Debugging c. Compiler VII. Other Topics d. Java Integration 17. Security e. JRuby API 18. Application Servers/ f. Extending JRuby Frameworks 19. Swing 20. Tools In late 2007, the JRuby core team decided it was time for an official book. Here was an early outline. This would have made for a great book, but we didn’t have the time to write a work this ambitious. We needed to negotiate scope.
- 19. IT’S NOT A WRITING GIG IT’S PROJECT MANAGEMENT Lesson #2: This project was as much about management—breaking down work, making hard decisions—as it was about writing. This was yet another thing I failed to realize early on. We spun our wheels for a while because no one was making project-management decisions. One thing we did get right though: we narrowed the scope down to something we could finish together.
- 20. At RailsConf in June 2008, the five of us sat down at the awesome Doug Fir Lounge in Portland to see if there was enough rapport for us to work together. This is a scan of the original notes I excitedly took.
- 21. notes, transcribed I. JRuby III. Appendices 1. Basics / Installation A. Ruby 101 2. Java from Ruby B. Contributing 3. Ruby from Java 4. Compiler II. Libraries 5. Rails 6. Hibernate 7. Rake 8. Swing 9. JMX 10.JMS This is what those notes look like when arranged hierarchically. It’s about half the size of the original plan.
- 22. the final book I. JRuby III. Appendices 1. Basics / Installation A. Ruby 101 2. Java from Ruby B. Contributing 3. Ruby from Java C. Configuration 4. Compiler D. C Code E. JMX + Sysadmins II. Libraries 5. Rails 6. Hibernate + Databases 7. Rake + Deployment 8. Testing 9. Swing 10.JMS And here’s the final structure of the book. We were able to stay pretty faithful to our vision for two years, because it all came from our simple mantra: using Java from Ruby, and Ruby from Java.
- 23. FOCUS ON A SIMPLE RALLYING CRY Lesson #3: avoid scope creep by asking of each proposed addition, “Does it help us do the thing we set out to do?”
- 24. work vs. “work” After the meeting, we set up our tools based on the way we expected to collaborate: IRC for conversation, Google Groups for files and wiki pages, and so on. Alas, none of these things are work.
- 25. DON’T CHOOSE YOUR TOOLS BEFORE YOU KNOW WHY YOU NEED THEM It should have been a yellow flag that we were choosing tools based on how we thought we might work, rather than on how we were actually working.
- 26. things we tried • IRC • Google Groups • Skype + Audio Hijack IRC was great for helping real JRuby users, but for a small group like us, there was never a critical mass in the channel for our book. Google Groups was also overkill for the kinds of informal things we should just have used e-mail or AWS for. Skype helped us get unstuck, but there was little point in recording it.
- 27. things we didn’t try • actually writing Okay, so maybe we wrote after all—it just didn’t feel like it.
- 28. AN EXPERIMENT THAT PROVES A RESULT YOU DIDN’T EXPECT is still A SUCCESS It’s okay that IRC and some of the other tools we tried didn’t work out for us. It was still a valid experiment to try, as long as we cut our losses and moved on.
- 29. harshness of reality It’s at this point that we near the second phase of the project...
- 30. trough of sorrow Wiggles of False Hope Trough of Sorrow Nagging of Stakeholders Abandonment? ...the Trough of Sorrow. This is where it looks like there’s no progress—either because there is no progress, or because it’s all on things invisible to the reader.
- 31. July 2008 Jackie: What’s happening with JRuby? Ian: Nothing. I have no authors. Couldn’t track anyone down.... Jackie: Can you try again this weekend? Don’t get discouraged just yet. This phase is best told in conversation. Notice that at this point, I still haven’t learned the famous Apple dictum: when you’re the one coordinating the project and it goes off kilter, “reasons don’t matter.”
- 32. August 2008 Jackie: Anything happening with JRuby? Ian: Good news from Sweden. Ola’s starting the chapter on Hibernate.... Aha! Forward progress!
- 33. September 2008 Jackie: BTW, if nothing is happening, we should talk about it soon. Ian: Ola just released a bunch of code... following up to see if he’s ready to write about it.... I’ve just proposed a “bookfest” where... we sit and do nothing but write.... Infrastructure progress isn’t always visible to the reader, though. Note that this is the first time we get the idea to write in person together. We’ll revisit that idea several months later.
- 34. October 2008 Ola: It seems that the book will take a long time to get finished..., and I really want to get going.... Ian: It's just been difficult [for the team] to justify writing about JRuby when they could either be hacking JRuby or helping someone.... On the other hand, a phone call gives us a solid block of time with each other, where we have (nearly) 100% of one another's attention. Four months in, and even the five authors are getting antsy—but we don’t know what to do about it yet. We have, however, discovered that voice chat is much less distraction-prone than text chat.
- 35. February 2009 Jackie: Is [Ola’s testing chapter] ready for me to review? .... This looks really good! Not much progress expected or seen during the Thanksgiving/Christmas time period. And then, in late January: a wiggle of hope!
- 36. April 2009 Jackie: How is it coming along? Ian: I feel a bit stalled..., and now things just seem... slow. Jackie: How can I help you get back on track? Are you getting discouraged? Two short months later, and we were close to abandoning the project.
- 37. http://www.flickr.com/photos/danielygo/5242003647 I’d love to be able to tell my past self: in any long-running project, there will be times when you feel alone. You’ll log into Skype, and no one will be there. You’ll send e-mail, and no one will answer. Don’t give up, don’t despair, and don’t give up.
- 38. http://www.harpercollins.com In The Care of the Soul, Thomas Moore explains that there are a lot more facets to the Narcissus myth than just some vain guy staring at his reflection.
- 39. SELF-DOUBT IS A FORM OF NARCISSISM In particular, self-doubt is a form of narcissism. Telling oneself, “I’m terrible at this; might as well give up” is just looking for an excuse to give up. Who would blame a terrible writer for not writing? It’s important to acknowledge these feelings for what they are, and then push on.
- 40. establishment of rhythm Release! Conservation of Momentum Establishment of Rhythm Right after near disaster, a few things happened that helped us establish a rhythm—both in the sense of playing well together, and in the sense of delivering at regular intervals.
- 41. a personal inflection point First, JRuby helped me out of a jam at work. I started using it as my primary Ruby, instead of using it as an interesting alternative. When you write about something you use all the time, you can write with much more authority. See Charlie’s blog entry on writing vs. implementing: http:// blog.headius.com/2007/09/are-authors-technological-poseurs.html
- 42. EAT YOUR OWN DOG FOOD Companies call this “dogfooding”—actually using the product you’re trying to persuade people to adopt.
- 43. three things to establish rhythm There were three more things we did together as a team that were crucial to getting us moving again.
- 44. HAVE A HEART(-BEAT) The first was to establish a heartbeat for the project. (No wonder the patient almost died—we’d never taken the pulse!)
- 45. Pivotal Tracker We broke our work down into a piece at a time—no time estimates—and entered them as stories into Pivotal Tracker. For example, a story title might be “Section on Maven describes Rake integration.” After a few weeks, Tracker would tell us if we were going to make each deadline. We got better at making them.
- 46. MEET IN PERSON AT LEAST ONCE The next thing we did was finally follow up on our plan to sit in person and write. I flew to Minneapolis and wrote with Charlie and Nick around dining room tables, coffee shops, restaurants, and bars all over the twin cities.
- 47. Google Docs We needed something more immediate than revision control so we could see each other’s changes. We turned to Google Docs. Notice we’re choosing our tools based on need now, not guesswork. We wrote about JRuby as we wanted it to be; if a feature wasn’t implemented yet, we’d throw a TODO in the text and keep writing.
- 48. FORM GOOD HABITS NOT EMPTY OBLIGATIONS The third thing we did was to establish Skype calls every Monday, Wednesday, and Friday after the writefest. We weren’t overly rigid about this. If we had nothing to talk about, we’d skip a call. If one of us had to be somewhere loud, we’d use iChat instead. The point was to form good habits, not empty obligations.
- 49. August 2010 Ian: The final chapter is in our editor's hands. The book is written. Tonight, I'll try this "sleep" thing I've heard about. We kept these habits up for a year. During that year, we announced the book, released several beta versions, and made tons of improvements based on our readers’ feedback.
- 50. lessons and hopes In the course of writing this book, we learned the importance of recognizing software management when we see it. We learned the importance of in-person meetings, even for remote teams. We learned how to establish and keep a rhythm, even when we’re geographically separate and extremely busy. We hope that there’s something in here that you can apply on your next freelance, collaborative, or remote project.