FLOSS Manuals

 English |  Español |  Français |  Italiano |  Português |  Русский |  Shqip


BookSprints: AdamsPonder

Adams Thoughts

Heres some thoughts from my experience leading sprints. Much of my inspiration for running events comes from seeing Allen Gunn (Gunner) in action with Aspiration Tech events. My experience in running these events has been a process of taking the intent of Gunners methodology and working out a way for it to work within a different context, namely the collaborative authoring of comprehensive text. Although I haven't tried this yet, I am very sure this method has broad application beyond the writing of Free Software manuals.

Writers vs Contributors

I prefer to refer to people that contribute to a manual as a 'contributor'. Sounds pretty straight forward but it can be tempting to use the term 'writer'. This, I think, is a mistake as the central tenet of FLOSS Manuals is that anyone can contribute to the Free Software movement, and they can do this by contributing to free documentation. Contributing can mean adding images, writing, editing, checking for technical accuracy, copy editing, hosting sprints, organising sprints, designing icons, designing covers, spell checking, changing the tone of a sentence, or reading the documentation and asking questions.

When describing the task at hand at the beginning of the sprint I prefer to use the more inclusive term 'contributor' than 'writer'.

I also prefer not to use the term 'author'. Although I respect the tradition, the term has taken on unnecessary baggage. Except for the few enlightened authors the term implies someone who works for a publisher, participates in a publishers star system, owns the copyright for their texts, licenses content as 'all rights reserved', and chases away attempts to alter their work. There is no place for 'authorial' attitudes of this kind in a collaborative writing environment. More enlightened authors, or those wanting to broaden their horizons are always welcome!

Team Development

One of the most interesting things about Book Sprints is the intensive social experience. This not only leads to very good conversations, which in turn lead to good content, but it is very common for strong bonds to form amongst the team.


I think a more accurate term is 'comprehensive text' - this is really what FLOSS Manuals is trying to produce. One storage and display medium for this material is a book, another is a webpage etc etc. Still 'comprehensive text' is too unwieldy a term so I don't use it much.


What is a publisher these days? I have no concrete answer to this. All I can say is that FLOSS Manuals is not a publisher in the traditional sense, we are working across many paradigms, and mixing them up as needed. That leaves us somewhere inside the publishing sector but outside the traditional processes.

Living Texts

In my opinion a text has a better chance of being born and living if it is collaboratively written. Often authors feel protective about their text and this often hinders the ongoing development of the work. Hence this kind of material is more likely to 'die' from the author protecting it whereas a text that has been sourced from a collaboration has a better chance of living because there is no one fending off contributions.

So when you start a sprint make sure you emphasise that all authorial egos must be left at the door.

To this end it is necessary the any text generated is created under an open license.

Food and Venue

If you provide a good venue, and good food you will not only have a bunch of happy sprinters, but they will want to do it again :)


Creating the Index

The Index is the skeleton from which a sprint must build a body of content. Unless it is impossible, the Index should be created by the people at (in the real space of) the sprint.

I have found that when we meet on the Sunday night before the sprint we can top the index off in about 3 hours. Having everyone at the sprint involved in the process of creating the Index is important for the following reasons :

  • everyone at the sprint understands the job at hand
  • it creates buy-in by all participants
  • it creates a good dialog from day 0

The Index should be necessarily vague. It should just be a series of section headings and chapter headings. You can use the Index tool in FLOSS Manuals to create this or you can use sticky notes and put them on a wall with the section headings and chapter titles.


Anything with more detail will only confuse the team. The content should be worked out dynamically as the sprint goes. The sprinters should just be able to write on Monday, 9am with a clear head. It's far far easier to get them started and bring everyone inline as the week goes, rather than shackle everyone with constraints on what must be written where and when - this is my strong opinion, based on the experience of many sprints, but i do acknowledge that I haven't tried the later approach. My feeling is that it might work in some instances but you would have to think about this carefully.

Combining another Event

For the Open Translation Tools Sprint we followed a 3 day conference (hosted by Allen Gunn and Aspiration) with a 5 day sprint. Since the topic of the conference and the sprint were the same we decided to integrate the two as much as possible. For this I built an outline on the wall of the Index with sticky notes and asked people to add/subtract/change the outline as they saw fit. At each session I also demonstrated the FLOSS Manuals tools so that those that did not attend the sprint could get enthused and particpate remotely.


The methods we started to develop here can be taken a long way but I learned a few things from this experiment. This first is that about 10% of those that commit to particpate remotely actually do - which is still not bad. The second is that many people contributed substantial material that they had already written - this was great! Although we did not use much of this material some was very useful and very well written. It took 2 days of non-stop reminding people of what we were doing for some of this content to emerge so don't give up!

Narrative Flow

The narrative flow of the text should be simple. Keep the text linear, progressive and broken down into clear standalone chunks. Each chapter should follow on from the last and lead to the next. Fundamentals at the beginning, leave no term unexplained, and ramp up the complexity as the book progresses.

If you do this the newbies can start at the beginning and the experts can jump into the book from a later starting point.

Do not make the mistake of over complicating your narrative. For example, the idea of weaving thematics or case studies through multiple chapters is going to make it harder to make the text harmonised and it will likely slow down the generation of content.  Also, any interweaving of themes that requires dependencies (ie. the requirement to read specific chapters before reading a chapter) will not be able to be re-used within another context very easily.

Getting People Started

Enabling written contributions from people who do not see themselves as 'writers' is a very important part of the Sprint process. There are a few important ingredients, the first is that people should feel comfortable, unstressed, and in a good mood. Its not always possible to manufacture this, but making it true for as many of the participants as possible is a neccesary role of the organiser. Secondly, people should write about what they know. Like talking, writing is easier if you know intimately what you are talking about. Also, like most things, its easier to keep people going if they are allowed to get immersed in their subject.

Inorder to do this, it is very important that participants start the sprint by choosing the chapter that most interests them. Let everyone start off in a somewhat random manner - don't worry about this, over the course of time the writing will become more co-ordinated. It is something like the start of a formula 1 motorbike race - all the riders run for their bikes and just get going, it seems like chaos at first, but over a short time things sort themselves out. The important thing is that people just get into it, forget their personal belief that they can't write, and just start writing.

For this reason also, it is important not to overburden the beginning of the sprint with writing rules. The process of improving writing style should occur organically - this can happen through discussion with the other participants and each individual contributor thinking about their own style, looking at the work of other, and changing over time, or the writing will improve by others re-writing content or the editing process.

So, start as unburdened by rules as possible. Of course, someone will likely ask 'where is the style guide' - for this purpose each manual has a style guide but it is linked to another page and not a very present part of the manual home page. So, those that want rules, can have them, but everyone else that doesn't want to think about these issues can safely ignore them.

Writing as Conversation

"Writing as a conversation" is a statement by Anne Gentle. I can't speak for Anne, but for me this statement has a very clear and important value in Book Sprints. The conversation takes place on at least four levels :

  1. the conversation in the room. With all participants seated around the same table conversations need to be fostered. Unlike traditional writing processes, this is a noisy environment and chatter should be encouraged. It is through these across-the-table conversations that the participants are harmonising their ideas about what they are writing.
  2. the conversation in the text. The texts themselves are conversations. Do not be protective about the content you contribute - encourage others to read it, change it, delete it etc. The continual combing through of the content by many eyes ("Many eyes make bugs shallow") is a fundamental tenet of Free Software and serves equally well in this environment. This constant changing is itself a conversation happening in the text and it is essential for improving and harmonising the content.
  3. the conversation outside the room. Be in touch with people outside the room and ask for their take on the texts. It is important to know if the texts really are going in a direction that can be understood by people that have not been privy to the conversations in the Book Sprint room. Encourage remote participants to feed back into the conversation via IRC, email, editing, and the FLOSS Manuals web chat.
  4. the conversation with the reader. When writing, use a direct and friendly and conversational voice. When I worked in radio one trick to getting DJs to relax and sound 'normal' on air was to cut out a picture of a face, stick it to the microphone and ask the DJ to talk 'to' that person. This worked. We tried a similar approach for the Circumvention Book Sprint by building readership profiles but I don't think it was effective (but it is an intriguing idea and I would like to experiment more with this approach). Andy Orams approach of writing a sample chapter with the desired tone is the best experiment yet for us in this area but we need to test it more. The same effect can possibly be achieved by encouraging contributors to think of the reader as someone they know well and respect. 

Disruptive Conversation

Occassionally you might need to deal with a disruptive presence. My experience has been that there are people who are so passionate about the topic at hand all they want to do is talk about it, and talk about it, and talk about it. This is not actually helpful. Although writing is conversational in this environment it is not a soliloquy or a monologue. This can kind of behaviour can be very disruptive and you will need to talk directly to the person concerned. This might be in open if done directly, but more effective is a casual but direct and clear communication with no one else around. Most likely if you break this issue gently the person concerned will listen and make good.

Gaining Trust

Its very likely that the group assembled to write a book has not done a Book Sprint before, or they may have never participated in a process orientated event. There is a good chance then that some of the participants will feel wary of this seemingly unstructured methodology. When you deliver the results this attitude will change - but that is at the end of the week...how to get through those first few days? Well, the only thing that I have found that will do it, is to feel strong within myself that I help will get them to the finish line. So, you have to feel confident. Don't let any nay-sayers get to you. If you don't have any tricks to help you through this then find them fast as you must feel confident when kicking it all off.

As for the nay-sayers. My preferred strategy is to joke with people to loosen them up. If someone is being uptight, its a good idea to gently make them conscious of this - not in a direct way, but with a friendly joking. The point is to chill them out, not to sit down and have a serious conversation about their concerns.

The Shape of the Week

So far my experience has mostly been with 5 day sprints with everyone arriving on Sunday and leaving on the following Saturday. Ideally we have a drink on sunday night and finish the index development. Monday morning is a quick tools demo and then we get into writing immediately. We write until Wednesday night, and then after Wednesday we freeze all chapters - no additional chapters can be added unless there is a absolute necessity. This means Wednesday night is usually the hard talk about what will stay in the manual and what will be thrown out. Everyone has to commit to finishing particular chapters by the end of Thursday. The Wednesday night talk also will include a slight restructuring of the manual to fit in line with any inconsistencies discovered and not resolved during the week.

Thursday is sprint within a sprint day. Everyone should write until they can't write no more. The aim is to get all content finished by Thursday night.

Friday is clean up day. 6pm open some drinks, make the pdf, upload it, buy a book, drink the drink.

Pairing it up

A great strategy that Michael Mandiberg (Digital Foundations) introduced into our process is 'pairing up' experts and non-experts.


Having an expert talking through concepts while the 'non-expert' asks questions and writes things down in a 'human readable' format can be very effective. This gives the newbie something to do which is more involved in the content than spell checking, and they learn a lot at the same time. It is also great for an expert to be confronted with difficult newbie questions - it forces them to confront their audience directly and break concepts down to clearer explanations.

Structural jams

You will surely get into a jam with the structure of a chapter, or the structure of the entire manual during a sprint. I recommend dealing with these issues as soon as possible. I have several review processes over the first few days - usually one at the end of the first day, and one at lunch the following day. The issues can be left to these meetings. Later in the process (after the second day) deal with issues immediately. If someone brings up an issue about the structure get those involved and any extra heads available to work it out.


A good strategy for reworking the structure of a chapter is to print it out, get a marker and some scissors and cut it up ...not really ala William S Burroughs, but in a more linear fashion. Chop out bits, rearrange them, cross out material that should not be there and then reflect those changes in the manual. For this process it is good to have someone take the lead (it does not necessarily have to be the sprint leader) and bring in people who are and are not familiar with the content of that chapter.


Harmonising Flow

Generally speaking the flow is taken care of by the conversations that occur in the room and the cross-editing that evolves from this. However in the event that you are working with a larger group the content generated might be too broad for much cross-editing and discussion.

To get a good flow between chapters in this situation I think its a good idea to assign the editing of a section to one specific person. After all the content has been written for a section get someone to read all the chapters and restructure/edit to make it sound like one person has written it as an evolving narrative. They may wish to write introductions and endings to each chapter to help connect the flow. Be careful however not to make these connections to specific as the material has to make sense if it was read by itself or in another context.

There is no problem in then getting another person to go over the same material with the same brief. The more people you have going through 'complete' content, the better it will get.


I think manuals should be a good read. Generally speaking the tone should be chatty and engaging. I know many technical writers would prefer more procedural texts but I think this kind of information is better left for quick help wikis etc. FLOSS Manuals creates comprehensive texts and this is better suited for chatty discourse than stripped down help systems. Here are some examples of tone that I like in manuals :

Example 1

The first paragraph of the opening chapter of the FLOSS Manuals Introduction to the Command Line manual starts like this, note the very direct but intimate tone in all of these examples.

"Commands enable you to do all sorts of powerful things on your
computer. We'll demonstrate this by looking at an everyday task that
might be familiar to you. If you use a digital camera, you probably
have a folder full of images on your computer. Imagine you wish to
resize the image profile.jpg so it is 300 pixels wide and save it as a
new image called profile_small.jpg.

Using an image editing software, the steps you need to go through might look as follows:"

Example 2

From the How to Bypass Internet Censorship manual; an explanation of who controls the net :

"The full story of Internet governance is complicated, political and
still being actively disputed. This text is meant to provide enough
details to help you understand how certain aspects of the system affect
particular methods of restricting access. The key point is that, in
some countries, all Internet infrastructure is owned and operated by
governments and large regulated telephone companies. A government that
wants to block access to information can exercise direct or indirect
control over points where that information is produced, or where it
enters or exits the country. Governments have extensive legal authority
to spy on citizens, and many also go behind what the law allows, using extra-legal methods to monitor or restrict Internet use.


Book Sprints are more art than science. Don't make the mistake of over-formulating them. It is absolutely necessary to leave some chance in the system at every step except were organisation logistics are required (venue, travel etc). For the rest, who attends, the scope of the book, how the book will be written etc - cannot be strictly formulated anyway so learn to coach a dynamic process on the fly and resist any indoctrinated impulses to micro manage. If you do micromanage the quantity and quality of material produced will suffer.

Also, it is amazing what can happen if you let it.

Follow Up

I recommend you consider getting the book out there asap while the energy and enthusiasm within the sprint team is at its peak. My recommendation would be to do a quick edit, don't think too hard about it, check some of the formatting issues mentioned below, and get it out there. If you can commit to really pushing it by the end of the week you will harness the energy you have all built up during the past weeks. The longer you leave it, the greater the amount of energy that will dissipate and the less effective your marketing for the book will be. Things that need to be considered immediately after the sprint include :

  1. Who will be the maintainer(s)?
    Its a good idea to appoint someone (or more than one person) to maintain the manual - this doesnt mean writing the manual, but drawing others into the process and keeping an eye on updates. At appropriate moments this person should update the sources on both the static HTML manual, and the book sources on lulu.com
  2. Promotion
    The books uptake, and the value that the user base gets from it, is directly proportional to the profile and push you give it. My recommendation is that you use all channels that are personally available to each of the sprinters. My recommendation is to make it as high profile as possible. We have noticed significant improvements in uptakes of manuals when they are linked directly from the home page of the project. Personally, I feel if you can really push this the additional 'look what we did last week!' angle, you have a nice story to catch peoples imaginations. The longer you leave it, the less effective this story becomes. Fast results are also good for acquittal purposes if you have to show results to funders.
  3. Bookstore widget
    FLOSS Manuals has a bookstore widget (see http://www.flossmanuals.net/bookstore). You can put this in your website to promo the book. It provides a link to buy the book immediately (or download the free PDF).
  4. Formatting
    The printed manual will probably need a little formatting. If anyone wants to get stuck into this they can output book formatted PDF to check via Objavi:

There has been error in communication with Booktype server. Not sure right now where is the problem.

You should refresh this page.