FLOSS Manuals

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


BookSprints: PrePlanning


Although we have scheduled book sprints as little as three weeks after the decision to hold them, and have squeezed the necessary pre-planning into less than 2 weeks, we find that it's a good idea to allow at least a month for pre-planning. Remember that someone has to find a venue, that some people may have to make travel arrangements, and that the proposed contributors need to to polled for topics.

The Free Software Foundation and FLOSS Manuals planned a book (Introduction to the GNU/Linux Command Line) with very little time for pre-planning. But there were several mitigating factors that made it possible to pull the sprint together in that short time:

  • It was held concurrently with their annual conference, on the same grounds. This meant that it was easy to find space, the book sprint participants could mooch off the main conference for food, and many conference participants could take a few hours off from the conference to join the sprint.
  • The topic (the Bash shell and related command line issues) was familiar to the participants. This meant that an outline could be developed quickly (the initial version was created by one participant in about one hour).
  • The prestige and publicity strengths of the Free Software Foundation helped recruit excellent writers (most of them remote). As a side effect, this allowed the authors to produce a sizeable book--over 200 pages--in just two days (note : FLOSS Manuals books use a non-standard page size, 200 pages in this format equates to about 150 A4 pages).

One or more people need to be in charge of planning the event. The tasks include:

Obtaining funds
The exact amount of money required will depend on the choices made for venue (and can be kept fairly low), but the source should be identified early in the planning process.
Determining topic and scope
Although an organization may make a top-down decision that it needs a manual on a particular topic, it's a good idea to hold some discussions beforehand (over email, teleconferences, or on a wiki) to find out from the grass roots what topics need to be covered.
Writing the outline
Some sprints have started with detailed outlines (down to one or two levels of heading in each chapter), whereas others have started with a loose grab-bag of topics. We are still experimenting with finding the right balance.
Establishing tone and style
This is a very subjective task. You want to provide guidelines so you approach your audience in the same manner throughout the book, while leaving scope for each author to have his or her own voice.
Finding authors
Luckily, within any organization that commits to running a sprint usually there are some highly motivated and accomplished members who can be persuaded to devote a week to the project. Otherwise you need to start researching and finding the people out there that know a lot about the topic. A number of people may be recruited, partly based on their ability to travel and devote the time.
Handling logistics
This is a large area of effort that covers finding a venue, providing resources, and arranging for food. Once you know the geographical area where the sprint should be held, someone who lives there should take on this task and find helpers if necessary.
Anticipating post-sprint tasks
It's not too early to talk about maintenance, although the energy generated by the sprint itself will help recruit maintainers.

Obtaining funds

Where do you get the funds? We have worked with partners that have sourced funds from NGOs, a little from Google's Summer of Code Initiative, and we have also done some fund raising ourselves. It's hard to give any general advice on this as we are young at fund raising ourselves.

Determining topic and scope

The two big questions to answer before a sprint are:

Topic and audience
What problem are you trying to solve? This also necessarily involves discussion of audience (the goals and background of your intended readers.
This could be defined as "Knowing when you're finished." It involves an analysis of the topic to determine what you need to say, and some prioritization to give the sprint achievable goals.

Topic and audience

The topic may be determined by the person who conceives of the sprint. For instance, the first sprint at FLOSS Manuals started with a statement as simple as "this manual is going to be about Audacity."

Still, it's important to have a strong concept of whom you're writing for and why. For instance, to plan a manual about  Audacity (an audio editing tool), you have to ask whether your audience understands basic audio-related technical topics, such as sound quality and the characteristics of audio digital files. You also have to ask what you want to help them accomplish. Simple cutting? Multitrack editing?

A community can often contribute a lot to the choice of topic. Sometimes, project leaders may have heard requests for a particular manual and may know what they want to cover without further consultation with the community. But it can surprising what they discover if they throw a preliminary chapter list out for review.

Probably the most extensive discussion of topic for a FLOSS Manuals book came for CiviCRM. It has a large community spread over at least three continents, and about a dozen people participated in a mailing list to plan their sprint. When it became clear that many valid and useful topics were being floated by various leaders, we held a teleconference about ten days before the event to pare away topics and decide what was really the most pressing issue they needed to cover.

Some questions to ask about your audience might be:

  • What (if any) are the job titles they hold?
  • What organizations or groups (if any) do they belong to?
  • Are they amateurs with limited knowledge or industry professionals in the workforce? Some--such as students--may occupy an intermediate position.
  • What other publications might they read, or what subject matter should they already be familiar with?
  • What is their general level of computer literacy?
  • What operating systems are they most commonly going to use?
  • What preconceived notions might you have to dispel?

It is also always a good idea to have one person from that target audience in the sprint. For example, if the target audience is "newbies", invite a newbie to review each section. Instead of trying to imagine what level to pitch the material at, it is much more valuable to have a member of your target audience in the room to look the experts in the eye and say "I don't understand what that means". The experts may then have to recalibrate their tone. This is not to say that the target audience member is always right, but the experts have to justify their position when challenged in this manner, and that is going to lead to better texts.


Once a main topic has been determined, you need to decide what subtopics to cover. Each book needs to have a beginning--which represents what your audience already knows--and an end.

As an example of the relationship between scope and audience, the Command Line manual started with such rock-bottom basics as how to find the Terminal program on your graphical desktop. The editor who wrote the outline (Andy) realized that a simple task like finding the program that lets you run a command line could prove a stumbling block to our readers. Another introductory topic was to explain what sort of possibilities are opened up to you if you master the command line, so as to motivate people to read the manual.

To set the manual's scope, start brainstorming as far as possible before the sprint. Try to create an atmosphere of acceptance, so people's suggestions aren't rejected hastily. This pre-planning should also help you identify potential participants in the book sprint: for instance, the technical experts you need, and representatives of the target audience.

However, there are two constraints you must respect:

  • A sprint must ultimately have a limited scope. Because most books come out less than 250 pages in length, some worthy topics will have to be left out. At FLOSS Manuals sometimes we use a benevolent dictator approach, where the Sprint Master determines the outline shortly before the sprint. For the CiviCRM sprint, that approach was rejected, so we used another approach that worked well: the team that assembled to write the book decided on the scope during the first morning of the sprint.
  • You can include only the topics that the participants are competent to write about, and interested in writing about. Of course, you can seek other subject matter experts to fill in sections after the sprint.

Knowing how much you can accomplish in the short time you have during a sprint is not exactly a science. An experienced Sprint Master can help identify what's feasible. An experienced Sprint Master will always tell you anything is possible (especially if you have a lot of remote contributions)...but some things are more possible than others of course...

Keep in close touch with the project leaders who have funded the sprint during the pre-planning, and make sure they will be satisfied with the scope. The Sprint Master must get them to understand that there are limits to what can be accomplished in a week and within 160 to 250 pages. They also must understand that unexpected considerations may come up during the writing, and that they must trust the sprinters to collectively make the right decision about scope.

Writing the outline

Some FLOSS Manuals books start with a chapter devoted to an outline. It's useful to ask people to edit this. The outline not only reveals the scope of the book--by listing all the topics--but puts the topics in logical order. Other times the outline as been generated on the spot by the participants by using the Index builder.

How much detail?

At FLOSS Manuals, we're still working out the level of detail that an outline should have as we go into the sprint. Just as the sprint as a whole must strike a balance between being productive and having fun, the level of detail in an outline is a balance between giving people a guide about what to write and leaving them enough room for the spontaneity and creativity that produces the best writing.

A detailed outline has one potential benefit: authors who write up advanced material can take it for granted that readers will get the necessary background earlier in the manual.

For instance, in the Command Line manual, advanced chapters on scripting could be written quickly under the assumption that readers already knew the building blocks of scripts (variables, control structures, and so on). It would severely hamper the authors if they had to worry about whether their readers knew these building blocks. They might have wasted time writing up this material and exhaust the time they meant to spend on useful advanced topics. On the other hand, they might have left out important information and no one might have realized until afterward that a big information gap was left.

Still, it's a waste for the outline to include details that the authors will later ignore. Each author has a unique vision, and sometimes a structure that looks great in the abstract turns out to be inferior when it's fleshed out into a chapter.

Two potential hazards when building outlines are:

  • the outline might end up being too broad if too much time is spent on it - this can build up unrealistic expectations on how much content will be written
  • if the participants of the sprint are not the same as the 'outline builders' there will be a critical disconnect between these two groups that will need to be fixed
Both these issues have been solved in previous sprints (eg. Inkscape and CiviCRM sprints) by re-building the Index with all book sprint participants involved as soon as everyone arrives on site.


In FLOSS Manuals, the index is the set of web pages that make up the book. (This is different from the kind of index you find at the back of a print book.) When people visit the main page for the book on FLOSS Manuals, the index is the list of topics they see. The index also becomes the chapters in the book.

A Sprint Master or other team members often create an index during the pre-planning phase. But most sprinters end up changing the index radically, adding and removing sections as they encounter new needs. Everyone has to keep a very flexible attitude to the it as the sprint goes on. As one sprint participant said, "Its about the constantly redefining what complete is."

Establishing tone and style

A book can be frustrating if it switches tone in the middle. One author may write in a jazzy, loose style, such as "Don't panic--we'll reveal the wizardry in a minute," while another might write in a more formal style, saying "The following example is complex, but will be understandable by the time you finish the chapter." Each style is legitimate and useful, but the reader will feel queasy if the tone makes a big swing from one style to another.

On a larger scale, you want authors to make similar decisions about when to introduce background material, how to intersperse examples with explanations, and other issues of flow.

Each FLOSS Manuals book includes a chapter on Writing Conventions. However we don't believe its a good idea to push this on writers. The conventions are really there if someone asks for them. Otherwise we keep them out of the way and then tell them to just start writing.

However, if you do want to set some kind of style, perhaps the best way to convey tone and style is by example. Before the Command Line sprint, the editor Andy wrote a chapter in the style he wanted for the book. He also provided strongly worded advice about the style we were seeking in the Writing Conventions. Although we don't know how many sprinters read the sample chapter or the Writing Conventions, we found that nearly every contribution adhered to the guidelines concerning pace and the approach to the reader, a feat all the more remarkable considering the large number of contributors.

Finding authors

We have conducted a fair number of Book Sprints by now, and it always seems that we get the right people every time. The reason for this is because we allow those involved to decide what the manual will be about. If participants see that there is an area of documentation that needs to be covered, or they offer to cover something because they know about it, chances are good that they will write that material.

So issuing an open invitation is usually a successful starting point. However of course, there might be some people you think should absolutely be there. Then you need to make direct invitations.

Often, you probably won't get a choice. Seldom will all the people you want actually have time to come. Encourage your most valuable experts to participate remotely as time permits. This means playing a bit with the tools before the sprint, obtaining an account on FLOSS Manuals (if the sprint is using that site), logging in from time to time, and making themselves available over email or chat for questions.

Relationships among sprinters is also important, because a book sprint involves intense discussions under pressure How people interact therefore plays a large role in what you produce. For this reason, the process is largely reliant on the chemistry between people, which is never easy to predict. The Sprint Master will play an important role in conjuring this chemistry, but chance also plays an important role.

Don't be too prescriptive - let a little chance bring something interesting and unexpected.

Reuse Existing Content

It is important to spend time finding as much existing content as possible. Re-use; re-use; re-use. Search the web and book stores for related content and write to each of the authors to ask whether you can re-use it. If it's a FLOSS Manuals book sprint, it's good to explain that this is a not-for-profit good faith exercise. This will help some potential contributors understand where we are coming from and they might feel more inclined to give copyright clearance. It is also important to ask whether the material can be used under the license you choose (FM uses the GPL). 

If material is available and it is under a liberal license that permits free re-use, you don't legally have to ask for permission, but it's good ethics and fair treatment to write to the author and ask not their permission but their "blessing" to re-use the content. Many of those authors like to know where their content ends up and you might also find you have a new enthusiastic contributor come on board as the result of your communication. At the very least, they will probably tell other people about the project, and that's good word of mouth PR for you.

Getting existing material is important not just because it can contribute to the total content of the book but because it is motivating for the writers to see that some of the work has already been done before they start. In the end, the writers might not use the content but by then it has had its motivating effect. 

Handling logistics

You need to plan of the dates, location, and participants in the Sprint before you get very far. If a group of participants is identified early in the pre-planning, they may pick the bests dates and location for them. Other times, a few project leaders have to pick a date and place and then see who is available. Either way, you need to consider some basic issues. We'll cover some of these in more detail in the chapter on Logistics and Budget.

The choice should combine convenience for those attending, availability of space and resources, and attractiveness as a location. A section of this book is devoted to venue.
How will everyone get there? Will you find the funds for travel, or will the participants need to cover some or all of this themselves?
Where will everyone sleep? Will they pay for their own accommodations or will you find funds for it? Are the accommodations sufficiently close to the Book Sprint venue so that participants don't waste energy traveling every day. Do heavy snorers need there own room? Do you need to have a cooking space? The ideal venue has sleeping space for everyone, and cooking facilitities.
This concerns both physical resources--such as tables, chairs, and a screen for presentations--and computing resources, especially high-bandwidth Internet access.
Make sure the participants don't have to worry about where their next meal is coming from (and provide snacks too). Take into account health, pleasure, and diverse dietary needs.
Because you want participants to bond personally--and because they deserve a good time after their work each day--find extracurricular activities. These could be as simple as a walk around nice grounds if you're in the country, or as formal as a canal ride on tourist boats.

Anticipating post-sprint tasks

If you want the manual to grow you will need to ask yourself - who will facilitate this growth? You don't need to determine this before the sprint starts but it might be helpful. At most sprints identifying the person to take on the ongoing maintainer role is a natural product of the process.

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

You should refresh this page.