Wednesday, January 23, 2008

Writing a Book in Google Docs

Currently, my editor Brian Jepson and I are collaboratively writing the book (tentatively titled) Google Office Hacks by O'Reilly using Google Docs. I wanted to outline the process we came up with, and maybe it's helpful for you too for certain needs.

The outline

The base document we're working on is the outline. It's a linked table of contents which helps us to organize the broad shape of the book, and also see the status of progress. I've bookmarked the outline in Firefox and added a keyword shortcut within the bookmark properties, so to open it I just need to type "gohacks" into the browser address bar.

Each document, as you can see in the screenshot, includes a title, status information, and a snippet. (In Google Office Hacks, the different sections are called chapters, and each individual article is called a hack.) The hack title is bold, and – provided the article behind it is written already – links to the Google document in question.

We color-coded the status information to have an easy overview: green means it's the first draft, yellow means Brian edited this first draft, cyan means it's in second draft, and gray is for chapters which went into production status. These colors allow us to quickly scroll down the long outline and see where we need to spend our work that day.

To open a document from the outline, you can now simply right-click it and pick something like "Open link in new window" from the context menu (provided you have been granted the respective editing rights).

Tip: I originally wrote the outline in Word, and then converted it to a Google document. Bad idea! This brings a lot of minor formatting quirks which the document doesn't seem to get rid of over time. To avoid these quirks, better start out fresh, or only copy plain (non-rich text) content into documents. These days when working with documents, I'm usually cleaning small text snippets I want to paste into the document by first pasting them into the browser address bar, to then copy them again... this workaround turns the clipboard content into plain text.

The individual documents

Each document/ hack uses the basic same template. I didn't use the default Google document styling because I don't like the overlong line lengths it creates when you use a full-window browser, so I added a <div> wrapper using the "Edit HTML" tab. To re-use this template, I'm always opening an existing hack, to then pick File -> Copy document from the menu. (It happened before that I forgot this copying and overwrote an old hack with a new one, but gratefully there's a revision feature to undo this mishap.)

My document styling of choice is the following, but any other style can be used too, of course:

<div style="padding: 20px; width: 620px; font-size: 14px;"> ... content goes here ... </div>

The document layout this creates can be seen in the screenshot:

When I insert screenshots or other images into a document, I'm first saving them as non-color reduced PNG files in local folder, where each folder is named after the hack title. An image format like JPEG might be a bad choice as the compression is not completely loss-free.

Once images are included in the document I'm usually adding a 1-pixel black border by going to the Edit HTML tab. It would be nice to do this via the image inclusion dialog – in fact, it would be nice to have Google Docs templates so that layout preferences don't have to be adjusted every time! (Though in fact, one hack now in the book deals with having a bookmarklet grab the Document Object Model of the Google Docs webpage to then go through it via an XPath to add borders to images.)

I'm using only limited formatting within the documents, like Ctrl+B for bold, or Ctrl+I for italics. (Sometimes, oddly enough, your formatting commands are ignored though on certain text selections.) O'Reilly handles the specifics of the book formatting – for instance, Brian wrote a script to convert the documents to the necessary format – so I don't have to worry about this (phew).

The workflow

Once a document is written, I'm using the "Check spelling" feature Google Docs provides. When that's done, I'm saving a local backup by using the "Export as HTML (zipped)" option... just in case anything gets lost. Then I switch to the Share tab to share the page with Brian. Brian will then get an invite to the document and can take over from there.

There's one quirk here with sharing. I don't want to manually type Brian's email address all the time in the "Invite people" dialog, so I'm just typing "Brian" and then hope for the auto-completion dialog to pop up. Now, Brian doesn't use a Gmail address as his main email so I'm usually writing to his O'Reilly address. This makes Google Docs wrongly assume that it's not necessary to show that Gmail address of Brian in the auto-completion dialog.

The workaround? From my Gmail account, I have to sent Brian a couple of bogus emails to his Gmail account every now and then to force Google Docs to "remember" his address in the auto-completion dialog.

Once Brian finished editing a document – by correcting my English, fact-checking, adjusting style, adding Google Docs comments, adding knowledge and so on – he saves and goes to the outline to change the color and status message next to the article's title. When I see this I can then go back to work on the document and pick the Revisions tab, comparing Brian's latest version with my last version before Brian took over.

When you check a revision, you will see strike-throughs and different colors and so on to indicate what was changed. Unfortunately, when you want to follow-up on a change you need to leave the Revisions tab again and switch back to the Edit tab – and next time you want to go to the revision tab, you are again asked to select which two versions you want to compare. While it may be possible to open two windows of the document, that could also be risky as both may be auto-saving every now and then. It would be much more neat if Google would remember the last selection of the Revisions tab, so you would be able to quickly toggle back and forth between reading a revision, and making changes in the editing tab.

Naming the files

In the case of Google Office Hacks, I'm preceding all file names in the Google Docs file listing with "GOHacks". Short names are useful due to the limited screen space (so calling it "Google Office Hacks" may push important information in the title out of view). Also, I'm dragging them all into the Google Docs "Google Office Hacks" folder for better organization. Then, the title is extended hierarchically to read e.g. "GOHacks - Spreadsheets - Add live data to your spreadsheet" (where "Spreadsheets" is the chapter title, and "Add live data..." is the hack title).

I'm rarely spending too much time in the Google Docs file explorer though, as the outline document serves as our base for jumping to documents. However, the file explorer can be useful for searching. One thing you do notice with the Google Docs explorer is that it's quite wasteful about using screen space – too little of the files are shown, too much space is wasted on information such as the folder description (even though Google already slightly improved this situation in a recent update).

Pros and cons to using, say, MS Word

Working from anywhere: In theory, as the book is stored on the Google server farm and not your home computer, you can access and edit it from anywhere, like an internet cafe, or your friend's computer, or a public cafe with wifi. In practice, when writing a book you need to concentrate quite a bit. Some authors may be able to concentrate better when hooked up to their laptop in a public cafe, while others need to go have a non-changing, quiet place – like their home desk, room doors closed. If that's the case, then the "work from anywhere" bonus of online applications is somewhat lost. Nevertheless, the fact that Google Docs allows me to collaborate on the same document with my editor, who sits across the ocean, is a great benefit.

In theory, as the book is stored on the Google server farm and not your home computer, you can access and edit it from anywhere, like an internet cafe, or your friend's computer, or a public cafe with wifi. In practice, when writing a book you need to concentrate quite a bit. Some authors may be able to concentrate better when hooked up to their laptop in a public cafe, while others need to go have a non-changing, quiet place – like their home desk, room doors closed. If that's the case, then the "work from anywhere" bonus of online applications is somewhat lost. Nevertheless, the fact that Google Docs allows me to collaborate on the same document with my editor, who sits across the ocean, is a great benefit. Lack of features: Google Docs has much less features than programs like Word, which have historically grown over the years. In general I prefer a slim program to one that is so feature-cluttered, you will have a hard time finding all the options to turn off CRAP (Configurations Rarely Applied by People). However, every now and then you'll also bump your head against the keyboard because a really basic, needed feature isn't there... wishing Google would work faster on implementing certain stuff. We'll see what 2008 brings in this regard.

Google Docs has much less features than programs like Word, which have historically grown over the years. In general I prefer a slim program to one that is so feature-cluttered, you will have a hard time finding all the options to turn off CRAP (Configurations Rarely Applied by People). However, every now and then you'll also bump your head against the keyboard because a really basic, needed feature isn't there... wishing Google would work faster on implementing certain stuff. We'll see what 2008 brings in this regard. You need an online connection: Working with Google Docs requires an internet connection. In my case, I need this internet connection anyway – even if I'd be using something like Open Office – because I have to check Google's applications all the time to write hacks for Google Office Hacks. But let's face it, even if you're writing something not about the internet, it's really great to have search engines back up your knowledge. So to me, the prerequisite of having to have an internet connection is not a real downside; your mileage may vary (and who knows, Google may also release Gears-support for Google Docs in the future).

On the other hand, having an internet connection can also be distracting from your work, of course... when you find yourself surrounded by all the little attention grabbers like chat, email, and social news sites!

There are many other differences between the two programs. Google Docs is free, for instance, whereas Word isn't. There may be smaller differences in start-up times (Google documents could really use a speed boost in this regards). One other thing I like about Google docs, or most web applications, is that I can switch to the English interface; this makes it much easier to, for instance, communicate about the application in help groups, or search for certain things in regards to the application. (With my locally installed Word I'm stuck with German.)

Theoretically, with an online app you also don't need to handle file backups yourself, because the application provider does this for you; practically, it's always a little risky to fully depend on the web app to never screw up, so you may be handling backups yourself anyway. After all, it won't help you much to know that Google told you Google Docs is still in Beta when your data is lost.

>> More posts


