Sunday, May 09, 2010

On Writing a Book, Pt. 3 – The Tools (I)

This is part three of an ongoing series about my experiences while writing the MySQL Admin Cookbook for Packt Publishing. All previous parts can be found under the mysql-admin-cookbook label.

Even though I said I would be presenting things in mostly chronological order, I think after the previous - rather dry - part, a little more technical and fun information would be nice for a change: The tools used to create the MySQL Admin Cookbook (well, at least those used by Udo and me). To give a detailed account of what software products we used during the whole experience I will split this topic up into multiple posts. Otherwise it would just become either way too long or I would have to leave out too much stuff than I am willing to.

Writing Tools

Packt provided us with both Microsoft Word and OpenOffice.org document templates. Authors are free to choose which format they want to use - if you own MS Office and like Word, you can use that, but if – like us – you did never buy a copy from Microsoft and don't want to do so for the book, OpenOffice is fine as well.

I have been using a Mac as my home computer for quite some time now, and I remembered OpenOffice as being rather slow and not too stable. Admittedly that was the result of only a quick glance at it, because I had bought iWork with the Mac and had been using Pages to write my everyday stuff. I was not too impressed with OpenOffice, but quickly learned that the compatible Mac version called NeoOffice was way more usable.

The document template provided by Packt contained several paragraph and character styles with names like “Code in Text”, “Keyword”, “Command Line” etc. Packt recommended writing with these styles to get a basic idea of what the book's pages would look like in print later. Also the page size was set close to the actual books format, in order to allow for a good estimate of the page count.

Even though NeoOffice was generally doing its job, I soon started looking for alternatives for two main reasons:

  1. Speed

    Even though more responsive than OpenOffice for the Mac OS, NeoOffice still did not feel as snappy and responsive as OOo on Windows did. After several writing session during which I cursed more than once about lagging responses to my clicks and typing I decided I had to find something else for the remainder of the book if I wanted not to kill myself or the Mac.

  2. Distractions

    While at first glance it might seem like a good idea to write in a way that let's you keep a close eye on the page count and do some basic formatting “in-line” while writing, it turns out to be a huge distraction. Even though I tried very hard to not get lost in fine-grained formatting, I regularly found myself going back a paragraph, because I had forgotten to use the “Code in Text” or “Keyword” template for some SQL example or other element. Also I regularly spent way too much time tweaking table column widths or just plain fighting one or the other obvious bug in the word processor.

    So in addition to the speed issue mentioned earlier I figured it would take me far too long to finish a chapter in this manner. It is quite remarkable how much more productive I got once I stopped letting my thoughts and actual writing be interrupted by this constant formatter “background thread”.

I decided I would first write down the bulk of a chapter's content as a plain text file, using only the formatting tools available there: None. The only thing I did was separating paragraphs with blank lines in between and occasionally inserting easy to find tags in the form of ***INSERT REFERENCE HERE***. As nowhere in the real contents of the book you would find “***” this was very easy to locate later on using simple text search.

However, TextEdit - the Mac's default onboard text editor - even though more comfortable than Windows Notepad did not convince me as a heavy duty writing tool. After trying several options, including WriteRoom and a custom Pages template, I finally decided to buy myTexts which I also blogged about already. It combined the no-distractions-full-screen-writing with a nice automatic file handling which even relieved me of thinking about saving my material. Almost everything after the first chapter was written with this simple but powerful tool.

I kept one file per recipe written instead of one per chapter, even thought the tool would certainly have handled that well. But by keeping the individual recipes separate it became a lot easier to navigate and keep of track what recipes had already been written by just looking at the side-panel.

Once finished, I would just copy and paste the text in its entirety into the NeoOffice document and started a little formatting session. Once I had amended the original document template with some personal keyboard shortcuts for the style templates most commonly used I could manage to format a single recipe in maybe 5-10 minutes. Often I would first write several recipes in myTexts and then bring them over to NeoOffice in one go. I cannot provide any hard timings or comparisons as to how much time I saved writing in this manner, but I can firmly state that material written like that tended to be a lot more “production ready” than what I had written directly in NeoOffice earlier.

WriteRoom Screenshot

In fact, I have not since changed my writing habits again and continue to work like this whenever producing any sort of text longer than an email. I have since bought a license of WriteRoom as well and use them both sort of on a daily-mood basis. As a matter of fact, this very post is being written in WriteRoom right now :-)

Version Control

Both Udo and I being software developers we were already accustomed to the concept of using a version control system (VCS). More than once in my day job was I glad to have easy access to prior versions of files I had locally changed, but not necessarily for the better. So it was very natural for us to start using a VCS right from the beginning. Even before we started the actual writing we checked in all documents and files we had exchanged with Packt so far as well as the outline and all reference materials into a hosted subversion repository.

There are numerous choices for free or paid hosting services. A nice one that allows you to start for free and only pay if you need more than 200MB of space is http://www.unfuddle.com. We created a free account with a Subversion repository and used it till the end of the project. We were expecting to have to upgrade to a paid plan somewhere along the way, but in fact we were able to squeeze everything in this free entry level account until the book was finished. As for the choice of Subversion over other version control systems, it was merely a matter of what was available, and as we were dealing with ODT and other non-mergable file types we figured it would not make much of a difference. Of course, personal preferences vary - any other VCS, be it distributed or centralized, would work just fine. The key aspect just was having a (one more) off-site backup and the aforementioned ability to go back in time should the need arise.

Whenever we sent of a finished chapter or anything else important to Packt we tagged it in Subversion - which turned out to be really helpful during the final stages of the project. More details on how and why will be presented in one of the later incarnations of this series.

As for the Subversion client, this is a matter of taste as much as the VCS itself. If I remember correctly, Udo used TortoiseSVN on Windows, while I – after some attempts with various Mac utilities – stuck with Versions, a very nice and “Macintoshy” application.

Versions Screenshot  

Backup

If you have ever written a dissertation, thesis or the like you should already be paranoid enough to not trust any single machine to keep your data safe, be it from thieves, fires or even (most dangerous of all) your own stupidity. If you have not, you should quickly become paranoid, because even if you trust (which you should not) that your hardware will not fail anytime soon, and even if your house is right next to the police and fire department headquarters this will not prevent you from accidentally deleting the most recent version of the chapter you were just about to send off to the publisher. Or you overwrite it with an older version. Or you try to move a picture around in the word processor and it crashes horribly, damaging the file, or ... well, you get the point.

The following are the backup measures I take. It is, of course, up to you to decide which of these or others you want to employ, but regarding backup, my take is “the more the better”. I did not include the SVN repository here again, but of course it is a backup, too.

  1. File Name Rotation

    The simplest way to guard against yourself destroying your own work accidentally is to regularly save to a new file name. This of course does not play too well together with the myTexts approach where you do not actually see the regular “Save File As” dialog, but it is a good idea anyway. I got used to just append a number to the file name and count it up every hour or so. Of course I would save much more often than once per hour, having Cmd-S hardwired into my spine after every paragraph or so. But using multiple files locally is also a good protection against faulty software corrupting a file.

  2. Time Machine / External Hard Drive

    As a Mac user this is a no-brainer. Time machine runs every hour or so, backing up everything that has changed since the last cycle to an external hard drive. As a Windows user you do not have the luxury of having this built in to the OS, but a local external hard disk is a good insurance against a failing internal hard drive.

  3. Dropbox

    The free Dropbox service is easy to set up and automatically uploads any files you save in a specified local folder to their servers. Access is protected and it operates silently in the background. This is also great if you work on different computers, because it will keep them all in sync when they are connected to the same account. The free plan gives you 2GB of space, certainly more than you would ever need for your book texts.

  4. Offsite Online Backup

    I own a Carbonite subscription which will transparently backup all my files to their cloud service. There are a lot of these services with varying prices and services, but they all send your computer's files (not only one folder like Dropbox) to their servers. While not strictly necessary in addition to Dropbox, it does not hurt either. Any form of cloud-based storage, even if you just copied your files to an FTP server regularly, will protect you from fire, lightning strike or floods, thieves or any other physical damage to or loss of your equipment. I would never work seriously for extended periods of time on a machine that does not use some form of online backup.

One can hardly stress the importance of backups too much. For a very good concept called “3-2-1 backup strategy”, go to http://www.dpbestflow.org/backup/backup-overview#321 and start to live by it.

So much for now. This has already gotten longer than I had planned… The remainder of the tools and programs I used while writing the book will get their mention in the next part of this series.

No comments: