Off the Beat: Bruce Byfield's Blog

As a full-time writer, I'm skeptical of collaboration. I have collaborated, with varying degrees of success, but the process has always seemed too time-consuming to justify the results. Still, having just submitted my first command line column for Linux Pro Magazine, I was curious to see the results of the FLOSS Manuals' sprint to produce a book entitled during last week at the Free Software Foundation's (FSF's) LibrePlanet conference. And, having done so, I think I'll have to reconsider my position on writing collaborations. While the result of the sprint is not perfect, it is certainly no worse than many books written by a single writer.

LibrePlanet is the collection of speeches and workshops that surrounds the FSF's annual general meeting. The idea has been growing for at least a couple of years, but this was the first year in which the proceedings were actually given a name and advertised. The book sprint attracted at least five people working at the conference and an unspecified number of remote contributors, and, although the book was not quite finished during the weekend, enough was done that in the week since the gaps have been largely filled.

The Pros
The first thing I noticed about the book was its readability. Unlike many books about technical subject, this one is not written in the academic dialect, but some one that approaches spoken English. Sentences of under a dozen words are common. The tone tends to be casual without much of the wordiness that usually creeps in when efforts at casualness are made.

Just as importantly, the contributors seem to be keeping the audience -- presumably, those new to the command line -- in mind, another challenge that defeats most writers on technical subjects. Too often, writers forget that their readers lack their expertise, and lack any sense of what needs to be explained. By contrast, Introduction to the Command Line is explicit about what it is doing. For example, the opening pages define a command as "a file that can be executed," and describe white space as "blanks and tabs -- things that show up white on paper." With the same clarity, directories are described as "containers of files."

Along with this clarity comes a refreshing frankness. The introduction assumes, probably correctly, that its readers will usually be opening a command line, saying bluntly that only system administrators are likely to otherwise these days. Then, after proceeding to explain how to open a virtual terminal in Ubuntu (probably not the FSF's preferred distribution to use as a reference point, but perhaps justified on the grounds of popularity), the introduction admits that the terminal doesn't give you much help at first glance. "You're expected to know what to do -- and well show you," the introduction explains.

Similarly, when talking about the output of ls from the root directory, the manual is careful to say, "You may see some files or directories in your root directory not discussed here. For now you only need to be concerned with one directory: your home directory. . . . Most of the time you don't need to know about the directory structure outside your home directory, but this knowledge occasionally comes in handy." What readers might wonder about is almost always carefully anticipated and voiced, and what the manual expects of readers is, as well.

The Cons
Unsurprisingly, considering the conditions under which the book was drafted, these virtues are not found throughout the book. Once or twice, contributors are unable to resist indulging in their own cleverness, as when the section on directories begins with, "Willie Sutton robbed banks because that's where the money is, and we'll examine directories here because that's where the files are" -- a reference that presumably sounded clever or humorous to the writer, but which almost everyone under seventy is likely to miss unless they quickly scurry over to Wikipedia.

More importantly, the continuity is sometimes lacking in the current draft. The large sections, which were drawn up beforehand, follow a logical order from the simplest concepts to the more advanced, but, within the sections, why one sub-heading follows another could frequently be clearer. But, given the multiple authorship, this problem is not surprising, and, can probably be overcome by a single editor going through the draft looking at nothing but continuity.

Another problem with the book is that the final section on scripting in various languages such as Ruby or Python is far too short. The section does not do anything beyond giving readers a few tricks. Meanwhile a sense of how the languages operate is largely omitted. For this reason, the scripting section is the one part of the book that could use expansion and more thought.

Conclusion
Introduction to the Command Line is not a finished work. In fact, its writing tends to get rougher the further you read, as though the first parts are the ones that have received the most attention so far. However, many parts of the book have been improved in the last week, and the improvements will undoubtedly continue. By the time the limited edition hardcopy version is released on April 6th, the text promises to be a good, brief introduction to a subject that is too often ignored in this age of the desktop.

If you've been thinking of brushing up on your language of the command line, or know somebody else who needs to do so, then Introduction to the Command Line is a painless and informative place to start, and proof that collaboration is no worse that single-authorship. And, while on the site, you might also want to look at FLOSS Manuals' other titles while on the site.

Comments