Tools and Processes for Collaborating on a Book Remotely

My last post was about the history of writing Getting to Know IntelliJ IDEA. Which was mostly for my own gratification, to help me realise just how much time and energy went into it. What people mostly ask me about, though, is the tools we used to write the book and the process we used to collaborate.

The tools

We wanted to use Leanpub to publish the book, because the royalties are generous, and we felt we could manage everything ourselves. It turns out to have another really nice benefit too, which is we can release updates to the book as soon as we need to, which helps a lot when the product moves as fast as IntelliJ IDEA.

Originally we started writing the book in Markdown (which we had been using for IntelliJ IDEA blogs) and using Leanpub's GitHub writing mode to build the book. We like using Markdown because we can write in IntelliJ IDEA using the built-in Markdown plugin and we can use all the standard editor functionality.

Using Leanpub in this way was going to cost money, and given all our false starts in writing a book, we were reluctant to spend money on something that might not go our way. We did need to be able to render the book quickly, ideally automatically, so we could see what it looked like as we went.

Josh Long suggested using Asciidoc with Asciidoctor, and pointed us to his Bootiful Asciidoctor pipeline, which would get us set up quickly with a book project and a GitHub Actions build pipeline that would build the book's artifacts (PDF, HTML, and ebook) every time we pushed our commits. This appealed to me enormously, I wanted to be able to see the rendered book easily, and I wanted to know quickly if we broke the book with some invalid syntax. This isn't so critical when you're writing a single blog post, because you can usually tell straight away if a single Asciidoc or Markdown file is incorrect, but when you pull them altogether with includes, code files, and images, it's much easier to accidentally break the book and not notice. Josh's pipeline supported writing code samples in separate GitHub repositories, which we could make public, and include the code in the book. This is exactly what we wanted.

A major selling point to us was that we could use the AsciiDoc IntelliJ IDEA plugin to write the text in IntelliJ IDEA and get immediate feedback on how the page was going to look. It has inspections which tell you when things are broken, it supports renaming and moving elements without breaking your book. It requires very little configuration to just work, and generally uses the same settings as the ones that are used when you build your book with Asciidoctor.

The process

In the early days, we had a weekly meeting of an hour to sync up. We'd share what we'd done, and work out what we were going to work on the next week. There were some weeks where this hour might be the only hour I worked on the book, but we made steady progress.

Once we had access to JetBrains Code With Me (which we were lucky to have early access to as employees), we spent more time remote-pairing on the book, which was much more motivating than working on it alone.

Our process, once we finally hit our stride, was this:

  • We scheduled a slot every Monday-Thursday to work on the book. By default, we would work together using Code With Me. Usually Helen would "drive" while I splurged out ideas and experiences on a particular topic. She'd make notes, although I'd often write stuff if I thought my fingers might know the words better than my tongue. She would ask sensible questions to get to the root of what I was trying to say (usually "but WHY do the readers need to know this?") and give her viewpoint on the topic.
  • If we had anything structural to do, like introducing a new topic, renaming things or moving things around, we'd usually pair on that with Code With Me to double-check we were doing something sane and make sure we hadn't missed anything. Small additions or changes could, of course, be done by us as individuals, but we'd usually ping each other on Telegram first to make sure the other was on board.
  • If one of us wasn't around for the slot, or if we both had individual stuff we wanted to work on, we'd use that time to focus on the things we wanted to work on alone. For me, that might be figuring out the detailed steps of a tutorial, for Helen that might be turning my nonsense words into prose that a human could understand. That's not to say that separation was absolute. Helen was vital to the tutorials as I'd often make assumptions about what was obvious, and she would work through them and flesh out missing steps or correct inconsistencies. I had to check any text which was a re-write of something I'd said, because my vague ideas would not always translate well into useful guidance for a reader. Part IV was very much a mix of us both writing our experiences from scratch and fine-tuning the other one's words.
  • Screenshots were my thing, so if there are any errors in the images they're my fault. I thought all my experience writing blog posts about IntelliJ IDEA for seven years would make the screenshots "easy". It did not. I mean, I probably got the IDE into the correct state faster than most would be able to do, especially for niche stuff (although you would not believe how much I had to Google or check the reference documentation, particularly when Helen asked me why a particular thing had to be done in a particular way or what a feature's actual name was).

We got together in person I think three or four times. Covid made that very difficult indeed. Neither of us travelled at all in 2020. When I went there in summer of 2021 we had to squeeze in a big re-org of the whole book (using Actual Bits Of Paper from a printed version of the book) while our husbands entertained my children with the Nintendo Switch. In November 2021, when Helen came to see me, the kids were so sick Helen and I had 3 days of writing the book on our respective laptops in front of the telly while my kids watched Disney+ and tried to rest. Then, when I arranged to visit Helen without children in October 2022 while we were both on "vacation", with the goal of Finally Finishing The Damn Book, she got Covid the week before. We had to remote-pair as usual, only this time I was at my Dad's house and Helen was trying not to cough all over her laptop.

What did we learn

  • That we work really well together.
  • Two heads really are better than one on such a huge topic with a broad audience
  • Dependency management has changed dramatically in recent versions of IntelliJ IDEA and it's much better than it used to be. I have forced myself to learn to use new approaches instead of doing it the old way.
  • Related: Some of my specific approaches have been superceded by "better" (or at least simpler) approaches. An example I can think of is using Search Everywhere instead of individual shortcuts for find file, find class, and find action.
  • IntelliJ IDEA is great for writing text. All those lovely editor shortcuts, like move line up and down, cut/copy without selection, delete line, and so on, all make writing English just as easy as writing Java. I think these tricks are not as well known as they should be, so I think you should all watch my video on Editor Tips.
  • There is an argument for using a publisher, because they can worry about proofreading, layout, image sizes etc. Of course you can do it yourself, you should ask yourself if you want to.
  • I learnt a lot about Asciidoc, asciidoctor-pdf, GitHub actions, Git (particularly how NOT to use it with binary files), the internals of Josh's Spring Boot pipeline app, writing and maintaining build scripts and performance tuning build processes in the cloud.
  • Self-publishing is probably more suitable if it's a topic you know well, if you're well-connected to others in the field (you need to find and manage your own tech reviewers), and if you have enough reach to market the book yourself. Leanpub has been excellent to us, they've reached out to help us market the book, but I'm not sure that would have happened if we hadn't shot into the top three books on the first day due to the fact Helen and I can easily reach developers interested in the topic.
  • Leanpub has a lovely advantage of being able to publish quickly as soon as you're ready. It means not only could we release the book before a new version of IntelliJ IDEA was released (something we would not have had control over with a publisher), but we can easily push out updates when we need to.

Buy Getting to Know IntelliJ IDEA, and give us feedback on what you learnt!

We covered a bit of our tools and process in this short (~10 min) video for Leanpub

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.