Book Sprints for technical documentation: from early beginnings in open source to tech giants

Many in the tech industry started out with FLOSS (Free/Libre Open Source Software) projects, and so did the Book Sprints method. And just like software development, so did the development of the method go through some trial and error, and some persuasion of early adopters, before it turned into a smooth and streamlined process. Experiments with sprinting FLOSS documentation started in 2008. By now, these experiments have led to Book Sprints being a premium service for tech giants and open source communities alike. Recent Book Sprints have included books on technical documentation with RedHat, Cisco, VMware, and the SPIFFE/SPIRE open source community.

The evolution of Book Sprints for software manuals

We talked to Book Sprints’ founder Adam Hyde about the motivation and the obstacles to developing a new method for rapid technical documentation, and how the method eventually got established in the tech industry. 

In the words of Adam Hyde…

Way back when I started a community called FLOSS Manuals I had one ambition – to make lots of free documentation of free software. Over a short time I realised there were three key ingredients to success – 1) collaborative publishing platforms (that didn’t exist) 2) documentation communities (that didn’t exist) and 3) rapid production processes for books (this also didn’t exist).

So I went about trying to solve all these problems all at once. One outcome was (eventually) Book Sprints.

Adam Hyde discussing the structure of a book for his Coko Foundation

From trials to the first Book Sprint

My first port of call was the publishing industry. I thought if anyone knew how to make books fast it must be them. Most of the advice I got from publishing folks required a process with a lot of overhead and some really disruptive editor techniques. It was just not working. I eventually resigned myself to the fact that I was going to have to fly solo and work it out myself.

So, I tried out a few experiments with friends – group efforts to write documentation. I got some ideas of how it was all shaping up and then wrote to a friend from the Open Source scene – Leslie Hawthorn (then at the Google Open Source Programs Office). Leslie backed the idea – paying for two more formal Book Sprints – one on PureData and the other on Inkscape. Probably the most effective Book Sprint from those very early days was the Inkscape Book Sprint. Held at the La cité des sciences et de l’industrie over a few days. We did actually manage to write a book which later became part of the Inkscape projects documentation.

Overcoming legitimacy challenges

I was up against two strong critiques from folks in the documentation/publishing/open source world. The first argument simply made the case that writing a book in 5 days was not possible. Countering this argument was simple – I just had to prove that it was possible. The second problem was more nuanced and interesting – at that time books were the business model for many folks that made open source software. The idea was to make a piece of software and then cash in reputationally and financially with a book released with a large publisher (mostly O’Reilly). I approached many open source projects to see if we could help write the docs fast through a Book Sprint and some key developer from the project would freeze me out. That happened a lot.

But over time I was able to find some projects that were keen and slowly the reputation of what I was doing grew. One of the big breakthroughs for me was when I was invited by the kind folks at CiviCRM to come to San Francisco and facilitate a Book Sprint for them – the big time!

From that Book Sprint I got more invites from Open Source projects – the power of word of mouth. Each one gave me more ideas on how to improve the process.

Books sprinted during a Google Summer of Docs

Taking off!

Another really important moment came when I proposed to Cat Allman and the folks at the Google Open Source Programs Office to do a Google Summer of Docs. We did three of them, with 3-5 projects Book Sprinting simultaneously. One of my favourite books came from that – a book on how to make fonts with font forge (an open source fontography tool). Through Book Sprints I was able to peek inside so many software projects and I always felt lucky to be able to do so but some events were special.

Then documentation Book Sprints really landed when (now a good buddy) Andres Vega from Cisco called me up. I thought it was a joke…Cisco? Really? Andres had heard about the Openstack Architecture book and was behind the idea. He had evangelised it within Cisco and they were almost ready to go… crazy… The first Cisco Book Sprint was almost as scary as my first Book Sprint with a room full of oil lawyers (by this time I had evolved Book Sprints to other domains outside of tech as well). It was scary and fantastic. I had gone into the room full of corporate devs thinking this was going to be tough. What do corporate folks know about collaboration? As it happens, it was one of the best Book Sprints. I unpacked my prejudice against folks working in corporations. You couldn’t have hoped for a better bunch of people and the series of really great Cisco books produced by many Book Sprints is good evidence of this.

The first Cisco Book Sprint in 2014

An established name and method

Since then Book Sprints has done a tonne of technical documentation. Many have made it into book stores near you and while most are distributed by the hosting organisations, some have been published by major publishers (including O’Reilly).

Now the talented team at Book Sprints do all the Book Sprints and it is a slick machine. I sit back and watch this incredible machine proving time and time again that fantastic books can be written in 5 days or less. And sometimes, just sometimes, I wish I was back in it – working alongside such a talented team and enjoying the privilege of peeking inside so many interesting software teams and projects….