BOOK SPRINTS
Command Line Manual
"I have written basic introductions to the command line in three different technical books on GNU/Linux and read dozens of others. FLOSS Manual's "Introduction to the Command Line" is at least as clear, complete, and accurate as any I've read or written. But while there are countless correct reference works on the subject, FLOSS's book speaks to an audience of absolute beginners more effectively, and is ultimately more useful, than any other I have seen."
--Benjamin Mako Hil
Some wonderful feedback about this manual...and what is more this manual was written in 2 days.
This sprint grew out of discussions that Adam had been holding for a while with leaders of the Free Software Foundation was considered from the beginning to be just the first project in an ongoing collaboration. The FSF expressed strong satisfaction with the outcome, but so far no second project has been planned.
The unusual aspects of this sprint included:
- It was squeezed into a weekend. (One other sprint has been done in two days since then.)
- There was very little time before the sprint, so pre-planning was compressed.
- The sprint was held concurrently with an FSF annual conference, and many people participated while taking breaks from the conference.
- An usually large number of authors participated, and more than half were remote. (We have not tried to determine what percentage of the text was contributed by remote participants, but certainly it covers several complete chapters.)
- The topic was very familiar and had been covered by a lot of existing documentation (including a very thorough man page and info page about Bash) as well as by many commercial books.
- The outline was written by a professional editor (Andy) who happened to know the subject well also.
Platform Development
For this sprint Aco replaced the hacky chat Adam had made with a more functional chat which interfaces with the FLOSS manuals IRC channel. This means that anyone can chat in the same IRC room using either the web chat in the FLOSS Manuals interface or their favourite IRC client software. Utlising the IRC like this was espeically important for this sprint since this is the preferred channel of communications for experienced users (ie. FSF super users).
We also added a mechanism for listing who is logged in at any given time.
Pre-planning
When we planned the sprint in March 2009, we had decided that it was important to provide detailed outlines for sprints. We have subsequently revised that dictum, but in this case it proved quite valuable because there were so many people converging on the book for such a short time. Also, the outline was easy to write: Andy produced the first draft in about an hour, and although other people added a few sections, but the first effort was pretty stable throughout the whole sprint. A few more sections were added during the sprint, and after the sprint Adam rearranged the order of many sections.
As news came in that people would be helping remotely, Adam realized that we'd have an unusually high number of concurrent authors, and suggested that we break up chapters into small files. This was good advice. The result is that this manual is broken into an unusally large number of separate web pages: about forty web pages for a book of 130 pages.
Logistics (venue, food, publicity) were handled mostly by FSF staff. Holding the sprint during their annual conference made these logistics easy to arrange (although, as we'll explain shortly, there was some confusion over logistics at the beginning of the sprint).
Publicity also turned out to be easy because the FSF has a large following. Because the topic is so thoroughly understood by free software users, many were happy to sign up for a chapter or more. Publicity consisted of:
- The normal announcement on the FLOSS Manuals site, plus a blog by Adam.
- An FSF press release that mentioned the sprint in conjunction with their agreement to form a long-term relationship with FLOSS Manuals.
- Another FSF announcement to members, inviting them to participate.
- Two blogs by Andy on the O'Reilly web site.
Some of these were picked up by outside observers, who endorsed the project in advance and gave it welcome publicity.
As he was living in the area, Andy tried to recruit personal contacts and colleagues at work. (He volunteered to do the coordination for the project on the FLOSS Manuals because he works in Cambridge. As it turned out, Adam came into town to lead the sprint and did more coordination.) Although Andy received some supportive responses from friends and colleagues, none of these people ended up attending.
Before striking a deal with FSF, Adam visited their Cambridge, Massachusetts office a couple times. Andy visited during the week before the sprint.
Andy's visit to the FSF office was definitely useful. Meeting some FSF staff he hadn't met before helped to build trust on both sides and make us work more as a unit. We also determined a couple last-minute needs for the sprint.
Andy also performed another unusual task before the sprint: he wrote an early chapter. His goal was to provide a model that would hopefully encourage other authors to meet the goals Andy set for the project:
- To keep in mind at all times that readers might be technical novices
- As a result, to move very slowly from topic to topic, explaining each new concept thoroughly
- To maintain a positive and encouraging tone that reminds the readers regularly that these topics are within their grasp
- To use many examples
Although each FLOSS Manual has a chapter on writing guidelines, Andy felt that something more concrete was needed to convey the goals to authors; hence the sample chapter.
Most of the submissions met these goals, although we can't determine whether providing a sample chapter helped to create the environment for this success.
Set-up
Several snafus slowed us down on Saturday morning when the sprint started: it was hard to figure out which rooms were ours, a class was being held in one room that had been promised to us, we had to put up directions to the rooms and had prepared only some crude signs with 8x11 sheets and masking tape, etc. None of these ended up being much of a problem.
Certainly, it's important to know the space beforehand (Andy at least had spent time in the facility), and it would have been helpful to plan more and prepare better signage.
We were also a bit worried at the start because only one person joined us. A couple others who came in later were willing to help but hadn't brought laptops. Andy offered his laptop out of politeness, but ultimately they decided they couldn't be productive.
But it was obvious from the start that many remote authors were busy writing, so Adam and Andy just had a good time writing, editing, and chatting over the IM interface of FLOSS Manuals. More participants filtered into the room.
Bandwidth, luckily, was ample on the wireless network, and participants on-site could use an account that the host venue (Harvard University) provided to the FSF conference.
Adam brought snacks to supplement the conference food (which was quite good).
Process
On the second day, several more people came to write. There were usually about four people in the room at any one time. Andy came at the beginning of each day, stayed for four or five hours, and logged in later from home. Adam was on-site the whole time. The number of remote contributors remained high.
Andy tried to focus on editing submissions, although his intrinsic love of writing often got the better of him and he would spend half an hour or so writing new material. Andy looked over the outline and existing chapters from time to time in order to find sections that needed to be written. Luckily, submissions came in so fast that we had to explicitly ask for help on sections only a couple times.
The manual was over one hundred and sixty pages in size at the end of the day Sunday, and all the sections except for two non-essential ones were considered ready for publication. Adam pushed the button and the manual went up for viewing and for sale. It was judged quite good by the FSF and others, and quickly made it onto a list of recommended free manuals by one third-party web site.
Post-sprint tasks
A few days after the sprint, both Adam and Andy looked over the whole manual. A couple other people, notably FLOSS Manuals member Ed Cherlin, also read it over and made contributions.
Ed wrote a good deal of a glossary, which had not received much attention during the sprint. He also made some suggestions and did some rewriting.
Andy harmonized the style in many places, removed a good deal of redundancy, and wrote a couple sections to flesh out one chapter.
Adam determined sections that should reordered, so that simple material came earlier in the book than complex material. Given the goals of "friendliness" that Andy defined for the book at the beginning, this was an important task.
Evaluation
The sprint was viewed by both FLOSS Manuals and FSF as an important indicator of whether we could work together. Both sides were very happy with the outcome.
Andy, who had originally volunteered because he was geographically in the area of the sprint, took on a leadership role as a proof of his ability to contribute professionally. As it turned out, the FSF handled the logistics, so Andy contributed by writing the outline and sample chapter, blogging about the event before and afterward, editing text during and after the sprint, and writing many sections. The amount of time he put in was definitely related to his desire to prove himself on his first sprint.
As mentioned earlier, Andy was concerned with making the manual very easy for novices, particularly people with a bit of a phobia about the command-line and related tools (such as text editors). It seemed like the book needed this extreme attention to usability in order to meet the needs of its audience. Andy also considered that many publishers had released well-regarded introductions to the tools in the book, which created high standards this book should meet.
As mentioned earlier, the vast majority of the authors picked up (from Andy, from each other, or just from common sense) the need for a slow pace and simple explanations. Thus, editing on most sections went quickly, although Andy and others would add new material as they went along.
It's possible that, as FLOSS Manuals becomes more well-known, sprints will increasingly involve large numbers of remote contributors as this one did. It's good to know that the book sprint process and the FLOSS Manuals web site can handle the flood. It would seem likely that, under these circumstances, the steps we took to prepare for the sprint contributed to its success:
- Provide a detailed outline
- Divide the project into many small web pages to facilitate concurrent authors
- Provide a sample chapter
- Edit early submissions quickly to maintain the goals of the project consistently
Outcomes
We now have two bueatiful books from this sprint - both with the same content. The Free Software Foundation released their own version of the manual with their own cover and are selling it from their site.
