Posted on by & filed under tools.

I just received my copy of Python for Unix and Linux System Administration by Noah Gift and Jeremy Jones, for which I was a technical reviewer. I’ve done several tech reviews for O’Reilly in the past, on both Python and CSS, and the least enjoyable part of the process has been the actual method of providing feedback.

At my previous job we routinely used Word (or OpenOffice) with Track Changes for collaborative editing, and as Word-based tools go I felt that worked well. For whatever reason, though, most of the pre-release books I’ve received have been in PDF, which is limiting in several ways:

  1. Cut and paste from PDF, especially of source code, often does not work properly. To test the code a technical reviewer needs to ensure that they are accurately repeating exactly what is in the book.
  2. There is no ability to in-line comment on particular words or phrases.
  3. The copy of the text I’m reading may be days or even weeks out of date, back when the author did the PDF conversion.

Python for Unix and Linux System Adminstration was different: the authors elected to use the source code control system Subversion to manage the writing.  The text was composed in DocBook XML rather than Word or some other non-text format.  While I’m sure this was done entirely to facilitate collaboration between the authors, it had the downstream effect of making it supremely easy for me to review it:

  1. Code samples were in plain text, and if they were formatted incorrectly, that was useful feedback to be able to give (especially in a language that is sensitive to whitespace, as Python is)
  2. While I was told I would be able to “commit” my changes back to the authors inside of the source text, I still chose to use an external file to provide my comments.  I did this only because I wasn’t sure that the authors would be able to manage multiple commits coming in from technical reviewers, and because we hadn’t decided on a common tagging framework.  With more editorial guidance, being able to commit my comments directly into the source could be very useful (including the ability to potentially see other reviewers’ comments, and avoid repeating myself).
  3. Each time I went to work on the book, I was able to get a fresh copy of the text.  I didn’t go back and re-check old sections, but it did mean that any section I worked on was always up-to-date.

When used with friendly front-end software like TortoiseSVN, Subversion isn’t even very difficult.  It’s certainly no more arcane than many professional content management systems.  Although it works best when managing text content (which could be Office-supported XML formats), it would still provide value with binary formats. It’s worth considering for any publisher that has to manage multiple, distributed editors or authors and wants to improve the process using entirely free software.

For more on the subject, Rachel Greenham has a nice tutorial explaining how authors can use Subversion with OS X. The definitive word is the Subversion book.

(I highly recommend Python for Unix and Linux System Adminstration as well, even for Python programmers who aren’t system administrators. It collects an impressive breadth of information in one place and showed me how to automate processes I hadn’t even realized needed automating.)

Tags: editing, Python, subversion,


  1.  Bookmarks about Book