As I mentioned in my last few (very sparse) blog posts, I’ve spent the better part of a year writing two books back to back – Professional Visual Studio 2010 for Wrox (as a co-author), and Pro Business Applications with Silverlight 4 (for Apress). How I came to undertake two books is a long story that I won’t go into here. Fair to say, I had no idea what I was getting myself into. Writing is a long arduous process of working seven days a week, pretty much around the clock, with pretty much no time for anything else in-between. It takes a huge toll on your sanity, and certainly isn’t worth it financially. Writing one book is bad enough, but two is pretty much insane.
I signed the contracts for the books (different publishers) at roughly the same time, thinking that I could do both books concurrently, but I was wrong. Luckily circumstances led to the Silverlight 3 edition of my Apress book being canned in favour of a Silverlight 4 version, meaning that I could do the two books back to back. Thankfully the whole process is now over (finally!), with the VS2010 book being released back in late April, and with the Silverlight book now in the production phase.
Anyhow, the purpose of this post is to provide other authors who might have made the insane decision to write a technical book with some tips that I’ve come up with along the way. If you’re an author too, I’d love to hear any other tips you have by leaving a comment.
Tip #1 – Harness Word’s Autocorrect feature for your own purposes
This is my absolute favourite tip. Unfortunately I only came up with it about 3 months ago, but since then it has saved me a lot of time and keystrokes. Word has an autocorrect feature that will take common misspellings (such as ‘teh’ instead of ‘the’) and fix it automatically for you. Actually the publishers tell you to turn this off (because it changes some character combinations to other characters that they don’t like/support), but my advice is to leave it on, and remove these mappings if necessary.
I was finding that I was commonly typing ‘Silvelright’ instead of ‘Silverlight’ (I’m not the only one who suffers this, as evidenced by typing the misspelling into Google), and decided to add it to the autocorrect in Word to save me manually fixing it. Then I had a thought. I could get the autocorrect to expand abbreviations for me. I could get Word to insert ‘Silverlight’ when I just typed ‘sl’. When writing a book on Silverlight, where I typed that name/word repeatedly, this was a big saving. Not only did it type the name right, but it also required just 2 characters instead of 11. Awesome! It was a major productivity boost. Other useful mappings include:
- Inserting multiple words with a single abbreviation – such as changing ‘ui’ to ‘user interface’, for example.
- Separate mappings for both the singular and plural uses of a word. The autocorrect kicks in when you press space at the end of the word. Therefore, if you use both the singular and plural of a word (‘application’ and ‘applications’ for example), map a separate abbreviation for each – ‘app’ to ‘application’, and ‘apps’ to ‘applications’.
- Inserting hyphens into words. You can get the autocorrect to insert hyphens where necessary – for example automatically change ‘plugin’ to ‘plug-in’.
- Inserting chapter references. In my text, when a concept was covered in another chapter, I’d refer to it like so: ‘as discussed in Chapter 10 – Advanced XAML and Data Binding’. Instead of typing this every time, I mapped ‘Chapter 10 – Advanced XAML and Data Binding’ to the abbreviation ‘ch10’. Of course, the name of the chapter ended up being stripped out in the copy editing process (making this example slightly less relevant), but you might find it worthwhile.
The possibilities are endless :), just as long as your abbreviation isn’t a word itself. For example, ‘vs’ would be no good as an abbreviation for ‘Visual Studio’, but you could preface it with another special character to make the abbreviation unique (for example, ‘^vs’).
To get to the autocorrect settings requires you to go through a myriad of menus and dialogs in Word, so I attached a keyboard shortcut to it. I attached Alt+Shift+T, though I can’t remember why I used that particular combination now. Here are some instructions on how to do so anyway: http://word.tips.net/Pages/T000425_Shortcut_for_AutoCorrect_Dialog_Box.html.
Caution: You get so used to using abbreviations when writing that you start doing it when writing emails, etc, and getting annoyed when they don’t expand :).
Tip #2 – Document Map and Styles panes
Another favourite tip of mine is to use the Document Map in Word. Go to the View tab on the ribbon, and select the Document Map check box in the Show/Hide panel. This will show a panel to the left of your document, containing its structure (based upon the headings used). This has two primary benefits. It will enable you keep track of the document’s structure, and also allows you to quickly navigate to a location within the document.
Another useful pane is the Styles pane, enabling you to select a style to apply to the text. Press Ctrl+Alt+Shift+S to display the pane. As the list of available styles can be rather long, you can filter the styles displayed to just those used in the document (by clicking on the Options link at the bottom of the pane, and selecting the In Use option as the selected styles to show), however filtering the list this way is only useful once you’re well into the document and have already used the styles in the document that you want available. Of course, even better than using the Style pane is if you can associate (and remember) keyboard shortcuts for each style. This makes things so much easier if you can.
In tip #7, I have a macro (to which I assign a keyboard shortcut) which sets the screen up just the way I like it, with these two panes visible.
Tip #3 – Use the Pure Text utility to convert formatted text to plain text
As a writer, you are constantly copying code and other formatted text into your document, where you don’t want to keep the original styles. You can always copy the text to Notepad first, but that’s a pain. You can use the plain text paste option in Word (using the smart tag), but that’s another annoying step too. The Pure Text utility however makes pasting pure text into the document much easier. It sits in your system tray, and when you press Win+V it will take what’s in your Clipboard and insert it into your document without the formatting.
Another side tip – rather than pasting code into the document, selecting it, and then setting the code style on it, simply set the code style on the line where you are pasting first, and then paste the code in (using the Pure Text shortcut). That at least removes the step of selecting the text for formatting.
Tip #4 – Use a guideline in Visual Studio to help you restrict the length of your lines of code
In order to fit within the width of a page, lines of code must be a maximum of 84 characters wide. Trying to check that you’re within this limit line by line is a pain, but you can use a guideline to mark out this point in the code editor in Visual Studio, which you can then keep within. There are a few ways you can do this, but the easiest way (now) is to use the Visual Studio Productivity Power Tools to activate and configure it.
To insert a guideline (assuming you have the Visual Studio Productivity Power Tools installed):
- Locate the position in the editor where you want to insert the guideline. You can see in the status bar what column number you are at, so keep going across until the column is showing 84.
- Right-click in the editor at this position, and select the “Add guideline” menu item from the context menu.
This will display a dotted ine at that position, as shown in the image below:
Tip #5 – Create a document linking all chapters
I found it handy to create a document that contained links to each chapter’s document. Initially, I had a document that I used to collate all the concepts and points I wanted to cover in the book. Whenever I came up with something that should be covered, I noted it down in that document. By rearranging the concepts and points into some sort of logical order, the chapter structure then started to form. This resulted in a document containing a heading for each chapter, and the concepts and points to be covered in a chapter below its heading.
When I created a document for a chapter, I would then link the heading for that chapter to the document. The steps to do this are:
- Select the heading text.
- Go to the Insert tab on the ribbon, and press the Hyperlink button.
- Locate the document to link to, and press OK.
This document then became a useful launch point to get to a given chapter. There are other ways to be able to easily open a given chapter, but I liked this method as I often had this document open (appending to it when I had new ideas for a chapter, and determining which chapter I wanted to reference in the chapter I was currently working on). I then pinned this document to the shortcut I had to Word in my taskbar (in Windows 7), so it was always easy to open.
Tip #6 – The Search Commands add-in for Word
Even after a spending close to a year working with Word 2007 as my primary tool, I still get lost finding various functions. The Search Commands add-in for Office 2007 luckily comes to the rescue, enabling you to search for the function you are after and activate it. This add-in can save a lot of frustration.
Tip #7 – Shortcuts, shortcuts, shortcuts (and macros)
Performing actions with the mouse is such a waste of your time, and having to constantly use the mouse to find and activate functions leads to frustration and a loss of concentration. Configuring, memorising, and using keyboard shortcuts is the solution to this problem.
Preconfigured Shortcuts
My favourite preconfigured shortcut is Shift+F7, which displays the thesaurus pane. Especially when I started writing, this came in very handy, as although I’ve always been well read and fairly good with the English language (spelling, grammar, correct use of there/their/they’re, etc), I’m simply hopeless at pulling the word out of the air that I’m after. I know the word I want, but I just can’t put my finger on it. Luckily I’ve improved in that area in the last year, but early on I’d often regularly refer to the thesaurus to try and track down the word I wanted to use. Another favourite preconfigured shortcut is Alt+P to insert a picture.
Configuring Your Own Shortcuts
One of the big problems with Word however is that it has so many damn shortcuts already configured, but rarely for the ones that you want to actually use. I ended up just setting up my own mappings, overwriting what was already configured by default. These usually consisted of Shift+Alt+ a meaningful key (though sometimes I omitted the Shift key).
In the reviewing process, the shortcuts that I configured and found most useful were Alt+. (to go to the next change, and Alt+, to go to the previous change. Why those? Well the characters above them are the angle brackets, so it was like pressing Alt+> and Alt+< to go back and forth between changes. It made sense to me at least. YMMV.
Writing Macros
I then took things further and started writing macros. Writing VBA code is no fun at all, so I tended to only do it when it would save me a lot of time. Usually I’d start by recording a series of actions to get some of the code in place, and then use that as a base to refine the macro. Some examples of macros I created are below.
Configure Your Workspace
An annoying thing I’ve found about Word is that it doesn’t really allow you to set up a workspace as such. Being a pedantic and finicky person, I want things set up the way I like them. Visual Studio remembers your workspace layout for you, but Word doesn’t. I wanted the Document Map and the Styles panes to appear (as discussed in tip #2), the zoom level of the document to be 100%, and the pictures to actually appear in the document (more about that shortly). Since Word didn’t remember this layout for me, I created a macro to set it all up, and assigned it the key combination Shift+Alt+C. This macro is below:
Sub ConfigureWordWorkspace()
ActiveWindow.DocumentMap = True
Application.TaskPanes(wdTaskPaneFormatting).Visible = True
ActiveWindow.View.Zoom.Percentage = 100
ActiveWindow.View.ShowPicturePlaceHolders = False
End Sub
The line to not show picture placeholders was due to me finding (for some unknown reason) that images weren’t appearing in some documents. This caused me a lot of frustration, and made me think that the document had become corrupted. I ended up discovering that there was an option deep in Word to turn off the display of images (on a per-document basis) that someone who opened the document previously must have turned on. I added this line to set this automatically for me.
Hide Changes (But Retain Comments)
The documents went back and forth between myself, the editor, the coordinating editor, the technical editor, and others, with the Track Changes feature turned on. As changes are made however, the document becomes really ugly showing all these changes. You can hide them easily by selecting Final from the Display For Review dropdown, but that also hides the comments, which I still wanted to see. To hide the marked up changes but keep the comments required a laborious process of unchecking the markup you didn’t want to see. So I wrote a macro to do it for me:
Sub HideTrackedChangesMarkup()
With ActiveWindow.View
.ShowInkAnnotations = False
.ShowInsertionsAndDeletions = False
.ShowFormatChanges = False
.ShowMarkupAreaHighlight = False
.Zoom.Percentage = 100
End With
End Sub
Insert Production Notes
This tip will probably only be of interest to Apress authors. Essentially we needed to include a production note before our images, specifying what image file needed to be inserted into the chapter at that position. This was another laborious task, so again I wrote a macro to search for the images in the document and insert a corresponding production note right before them. Yeah, I know the code is a bit dodgy (I banged it together pretty fast going for function over form), but it works:
Sub ReplaceImages()
With ActiveWindow.View
.ShowRevisionsAndComments = False
.RevisionsView = wdRevisionsViewFinal
End With
Dim chapterNumber As String
chapterNumber = InputBox("Chapter number:")
Selection.HomeKey Unit:=wdStory
Selection.Find.ClearFormatting
Selection.Find.Replacement.ClearFormatting
With Selection.Find
.Text = "^g"
.Replacement.Text = "[Some remembering if needed]"
.Forward = True
.Wrap = wdFindContinue
.Format = False
.MatchCase = False
.MatchWholeWord = False
.MatchWildcards = False
.MatchSoundsLike = False
.MatchAllWordForms = False
End With
Dim figureNumber As Integer
Dim isFound As Boolean
figureNumber = 1
Do
isFound = Selection.Find.Execute
If isFound Then
Selection.MoveLeft Unit:=wdCharacter, Count:=1
Selection.TypeParagraph
Selection.MoveLeft
Selection.Style = ActiveDocument.Styles("Production")
Selection.TypeText Text:="Insert 72076f" + chapterNumber + Format(figureNumber, "00") + ".png"
Selection.MoveRight
Selection.MoveRight
Selection.MoveRight
figureNumber = figureNumber + 1
End If
Loop Until Not isFound
End Sub
If any authors have handy tips for managing figures and their associated image files on disk, I’d love to hear about them. One of the most frustrating aspects of writing occurred when I decided to insert a new figure above numerous other figures already in the document. I’d then have to change all the numbering for the figures below it, and then update the file names of the corresponding files on disk. If I had my time again, I’d write a macro or something to help manage the images and their references intelligently. Unfortunately, I just never had the time to do so. Do you have a better process for managing this yourself?
Insert a Normal Quote Character
As a final tip, when you’re modifying code that you’ve pasted into Word, you don’t want to use Word’s smart quotes that it likes to use. Instead, you want to insert a standard quote character (“). I found it annoying having to copy an existing quote character from elsewhere, so again I wrote a macro to insert the character for me (which I assigned Alt+’ as its keyboard shortcut to quickly insert the character). My code for this macro is below:
Sub InsertQuoteCharacter()
Selection.InsertSymbol 34
End Sub
Tip #8 – Folder structure on disk
Staying organised when writing a book is vital. Otherwise, things will quickly get out of hand. For me, having a well structured folder hierarchy to maintain all the files associated with the book was a key step in staying organised. You can see the folder hierarchy that I’ve created in the image below:
A quick explanation of each:
- Archive – I dump files in here that I no longer want, or before deleting large sections of them. This is more or less redundant if you use Subversion for versioning (discussed in the next tip).
- Code – each chapter has a corresponding solution, each maintained in their own folder under this Code folder. I name the folders and the solutions like so: ChapterXXSample, where XX is the chapter number (with a leading 0 if a single digit, eg. Chapter07Sample).
- Drafts – the first drafts of each chapter go in this folder.
- Editor Reviewed – this and the Tech Reviewed folders should technically just be a single folder. The process is that you send your chapter away, the editor and the technical reviewer comment on them, and it is then returned to you for the final draft process. That didn’t quite work properly for me (long story, predominantly my fault), and I ended up getting each chapter back from each person separately. So I put the version from the editor here, and the version from the technical reviewer in the Tech Reviewed folder. Technically, this folder shouldn’t really exist. The single version you get back should go into the Tech Reviewed folder.
- Errata – I put documents containing the back cover text, preface, acknowledgements, etc in this folder.
- Final Drafts – the final drafts of each chapter went into this folder (i.e. those incorporating feedback from the editor, technical editor, and peer reviewer). Remember to update the document link in the document discussed in tip #5 accordingly. Tip – when you get to this stage, archive the corresponding chapter in the Drafts folder – it saves you accidentally opening the wrong version by mistake (especially useful when you forget to update the document link in the document discussed in tip #5).
- Forms – this is where I put my contract and other files I needed to sign and send to the publisher.
- Images – this is where I put all the images (usually screenshots) for the book. Each chapter has its own folder under this folder for their images.
- Peer Reviewed – “peer reviews” is a term I’ve coined for something that doesn’t really exist in the formal book writing process, but that I think should be (as I discuss in tip #12). Documents with comments from the peer reviewer go here.
- Planning – this is where I put the document discussed in tip #5, although it’s probably better if you place that document in the root folder instead. You might also want to use this folder for keeping schedules (dates due, etc).
- Production – when the book is finally complete, the chapters are sent back to the author nicely laid out, showing the results of all your hard work (as PDFs). This is where I put them.
- Tech Reviewed – as previously discussed, this and the Editor Reviewed folder should technically be the same folder. This should be the folder where you put the documents after they’ve been reviewed by both the editor and the technical reviewer.
In addition, I added the Silverlight folder as a favourite in Windows Explorer so I could get to it quickly and easily from various Open/Save dialog boxes. To add a favourite (I’m sure there’s an easier way, but this way works):
- Select the folder in Windows Explorer to add as a favourite.
- Now find the Favourites item near the top of the tree, right-click on it, and select the “Add current location to Favourites” menu item.
Tip #9 – Save early and save often
I’m a compulsive saver. Pretty much every sentence I add, I follow with Ctrl+S. Having lost work in years gone past from not saving regularly, it’s long since become a habit. Word does have an auto-save feature, but I take no chances.
Saving to your hard drive is one thing, but if that dies (and we’ve all had that happen and lost work to it) or gets lost then you’re in trouble. Therefore, regular offsite backups are essential. For the VS2010 book we used Live Mesh, and for the Silverlight book I used Dropbox. Both are quite similar in nature, but I switched to Dropbox for its versioning capabilities (which Live Mesh doesn’t have). In hindsight, although both worked well, I’d probably have just been better using a Subversion repository, which would provide proper version control features (and share this with the “team”). Assembla provides free and paid Subversion hosting (which I already use with clients, my team, and others, and have found really good).
Tip #10 – Capturing screenshots
Screenshots were the bane of my life when writing. Especially with the VS2010 book, as I’d take a screenshot for beta 1, but then it’d change for beta 2 and I’d have to do them again. Then the RC introduced additional changes, so I’d have to do them again. Each screenshot often required a certain amount of configuration, so taking them wasn’t a quick process. In addition, Windows Aero uses rounded corners, but when you take a screenshot of the window these corners are filled in black or a dark grey (and look horrible). So you have to edit these out, which takes even more time (as demonstrated in the image below).
SnagIt (from TechSmith) is a great tool to help produce screenshots, but is a little on the expensive side. Apparently, the newly released version 10 now (finally) handles this and fixes the corners (I’m still on version 7 though). That would be a relief and save a lot of time. If you don’t have SnagIt, you could use Jing (also from TechSmith), or one of the many other screenshot tools. SnagIt is definitely the best however. There’s another free screen capturing tool named 7capture which can remove the black corners, but I personally wasn’t terribly fussed with it.
I’ve noticed that Visual Studio 2010 and various other programs have some really weird windowing behaviour going on. I’d often use one of these screen capture tools to capture a given window, but it would cut off half the title bar or other strange behaviour. This makes taking a screenshot of a window even more painful, as you then have to take a shot of the whole screen and edit it manually to include just the window you are after. Anybody else have this problem, or is it just my system? An example of this behaviour is below, with the red box defining where SnagIt thinks the outer bounds of the window are:
Anybody have some tips in relation to taking screenshots?
Tip #11 – Dealing with a blank page
No matter how many times I started a new chapter, the blank page it presented me was always a scary experience. My brainstorming document that I discussed in tip #5 helped, because I could dump all the points from that into the new chapter, and work from there. The most important next step is to start building some sort of structure for the chapter, which acts as a framework where you can then fill in the blanks. Each chapter is kind of like a jigsaw puzzle. When you start a jigsaw puzzle, you typically dump all the pieces out on the table, start turning them the right way up, and find/connect all the edge pieces to provide a structure to work within. Writing a chapter is much the same process. Basically I start by performing a memory dump, putting everything relevant that I can think of randomly on the page (I tend to think of it as a “vomiting on the page” process, but that description hasn’t been popular with those I’ve shared it with thus far). I then take all these ideas and points, and organise and rearrange them to form a structure for the chapter. I can then expand on these to fill out the chapter.
I also try to ensure that I answer each of the following single-word questions in relation to each concept:
- What?
- Why?
- Where?
- How?
- Who?
- When?
What each of these “questions” refers to depends on the context, so I won’t expand upon them here. However, I think if you attempt to answer each question in relation to a concept, it will more or less ensure that any questions the reader might have about that concept will be covered.
One thing I noticed in my chapters was that they were very text heavy, and this was noted by others who saw the chapters too. When Greg Harris reviewed my chapters (see the next tip), he was very critical of this issue (rightly so). He forced me to introduce more sub-headings, and extract blocks of text into bullet points. Doing so helped a lot with the structure and readability of the book, and resulted in big improvements.
Tip #12 – Testing your book with a peer reviewer
Numerous people are involved in producing a book. As an author, I write the book, but you also have input from the editor and the technical reviewer, and the copy editor fixes all your grammar problems, etc. However, to me there’s an important piece of the puzzle missing in this process, and that’s having your book “tested” by the type of person who might buy your book. The technical reviewer is someone already familiar with the technology being written about, and “tests” your book – looking for incorrect facts, malformed code, etc. However, by knowing the technology well, they have pre-existing knowledge that influences how they perceive the book. Therefore, it’s very easy for them to overlook readability issues, where you might introduce (but not explain) a term that they are familiar with, and thus keep on reading, whereas a reader might come to it and think WTF?
Therefore, I think it’s vital to “test” your book with a newbie (or still in the learning phase), representing the typical person that might buy your book. I call these “peer reviews”, although there’s probably a better name for them. I was very lucky in that in the VS2010 book I had fellow co-authors with whom I swapped my chapters (we mostly were writing about technologies we were already personally familiar with, and swapped with someone not quite so familiar with those technologies), and then for the Silverlight book Greg Harris kindly offered his services to review my chapters (and did a fantastic job). Each peer review resulted in tonnes of fantastic feedback, and I believe the books are far better for it.
Tip #13 – Box selection
Not many people know about box selection of text. Instead of normal line by line selection like this:
You can hold down the Alt key while selecting text, to select it like this:
This works in both Word and Visual Studio. I’ve particularly found it handy when I’ve pasted indented code into Word, and want to remove the indenting back one level. Rather than deleting the spaces line by line, you can use this trick to select the indented space in all the lines, and delete them with a single keystroke.
The End
OK, that’s it for now. I expected this to be a short post, but it’s ended up almost being chapter sized (over 4500 words)! I hope these tips help you, and I wish you luck in your writing. If you have found these tips useful I’d love to hear about it. If you’ve got your own tips, please leave them in the comments! I might do another post sometime about the interesting things I’ve learnt along the way about the English language and structuring sentences. But then again, I’ve pretty much had it with writing right now, so we’ll see :).
Chris Anderson 