Andy Oram
March 23, 2009
I've just been through a marathon work experience--a book sprint, it's called--with intriguing and gratifying results. We tried to write a conventional computer manual in two days, and the experience has made me reconsider the conventions of computer manuals.
FLOSS Manuals, a young group devoted to "free manuals for free software," recently had a handshake with FSF and agreed to write an introduction to the command line. Many, many books have been published about Unix shell commands, of course. The FSF itself offers a comprehensive, well-structured, and clearly written info page about Bash. But the free documentation isn't friendly to new users; it doesn't sooth the fears or smooth the way for those who have a phobia about typing at a terminal. Hence the two-day book sprint for which I volunteered last weekend.
This was like nothing I had ever worked on. Software developers often hold hack-a-thons, but they don't expect to have a complete product at the end of two days. And the most grueling forced march O'Reilly ever put authors through still required a couple months.
The FSF's outreach skill matches their public respect, because in the few days between their appeal for help and the start of the book sprint, 130 new members signed up on the FLOSS Manuals site. Pages for the command-line manual filled up even before we started the sprint on Saturday. Hardly anybody joined us in the room on Saturday, but contributions poured in from around the world. On Sunday we had five or six people around the table writing, which was tremendous fun, along with more online contributions from people we knew only through brief IM postings.
The contributions were of uniformly high quality, an amazing achievement for which we are thankful. Not only was the writing clear and relevant, the authors additionally grasped our goal of keeping things as simple as possible and indulging in lots of hand-holding. I hope I can take some credit for setting the right tone, because I provided some conventions (my favorite directive was "Your goal in writing this book is not to give readers information"), wrote an initial outline that held up pretty well, and seeded the wiki for the book with some introductory text.
Now that the first draft is posted and published, we have to sit back and think of where to take the book next. That's the point where I'm re-examining conventions.
One of the hardest tasks in documentation is figuring out where to present background. Many documents ignore and omit it. Others inundate the readers with abstractions, driving them away from the book and perhaps from the subject forever. Few books achieve the right balance, and hardly any integrate the background gracefully with its practical application.
Even in submissions as good as the ones we received for the command-line manual, I was amused at how often authors said things like:
Before discussing the concept of "piping", you should know about standard input and standard output.
or
In order to work with the command line you need to know a little about the structure of the directories and files on your computer.
Not true! What the authors need to understand is that readers don't need to understand X before doing Y--usually. There are two principles that tell us to thrive on ignorance.
The first principle comes from John Dewey, an early twentieth-century philosopher whose doctrine of "learning by doing" still reigns in education. Dewey obviously didn't endorse ignorance; he just expected people to overcome it by struggling with a task. Learning by doing requires a faith that learners will bring intelligence and a sense of inquiry to their learning.
The second principle comes from Saul Alinsky, the inventor of community organizing. (He founded the Industrial Areas Foundation for which Barack Obama worked several decades later.) Alinsky said you have to meet people where they are, which means they can't absorb a concept "outside their accepted area of experience." He would illustrate the principle by having students watch him as he walked down the street and tried to give away a ten-dollar bill; no one would take it.
So powerful are these principles that I'm afraid even this blog is too preachy to achieve my purpose. So I'll just say to prospective authors: try embracing the reader's ignorance! See how little you can tell them. Encourage them to do something without understanding it.
Ultimately, yes: the book should give readers some guidance. After they've tried out pipes, they're ready for explanations. But that leads to my next challenge.
We're coming to learn that people can organize themselves in our interconnected world without forming rigid lines of command. For a long time I've suspected that books can be the same way.
Over a two-day period of intense book hacking, while chapters of the command line book grew with text as I jumped from one to the other, I hit a limit on how much I could organize the book. I had produced a detailed outline on the advice of my FLOSS Manuals colleagues, who had found outlines critical to earlier book sprints. When we got a hundred new sign-ups, I was advised to break the chapters into files and break them up again to facilitate joint editing. Finally, we were left with 169 pages of good material--all a jumble.
I wonder now how much we need to organize the files. The web has always been chaotic. Readers don't read it the way they do a book, and have been trained to find material instead of having it slide under their noses.
Might it be presumptuous to tell them they must read about standard input before piping? Even if were true? Could you trust them enough to throw them in the middle of the forest and have them follow the markers to the exit?
What readers do deserve is a set of supple and explicit references among documents, and I have recommended such a system.
The computer field is still in the kindergarten stage of exploring serious questions of how people learn, questions at the center of psychology and pedagogy for many decades. Even those disciplines don't quite get it, because they're fumbling with the instant messaging culture that gives us so many more tools today for learning together. I know I'll go back to the command line book eventually and straighten it out, but I have a feeling it will never be finished.