My Author Tips

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:

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):

  1. 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.
  2. 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:

  1. Select the heading text.
  2. Go to the Insert tab on the ribbon, and press the Hyperlink button.
  3. 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

    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

        isFound = Selection.Find.Execute

        If isFound Then
            Selection.MoveLeft Unit:=wdCharacter, Count:=1
            Selection.Style = ActiveDocument.Styles("Production")
            Selection.TypeText Text:="Insert 72076f" + chapterNumber + Format(figureNumber, "00") + ".png"
            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):

  1. Select the folder in Windows Explorer to add as a favourite.
  2. 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 :).

3 thoughts on “My Author Tips

  1. Chris invited me to contribute a few comments to his excellent post, so here they are.

    First, in response to Chris’s tips:

    Tip #3. Word has a way to set the default paste. For example, you can tell it to always strip the formatting out of text pasted from another program. In Word 2010, these options are in the Advanced section of the Word Options dialog box, under the “Cut, copy, and paste” heading.

    Tip #10. I’ll throw my vote in for WinSnap. I started using it because it was the first screen capture program to properly handle the dreaded window-corner problem on Windows Vista. It’s not free, but it is small and reliable.

    And a few more tips:

    Tip #1 – Get a writer’s toolkit
    Different books have different requirements. There are a few programs that I’ve found that are indispensable in certain situations, but thoroughly uninteresting the rest of the time. They include:
    * A file renamer. New book editions have new ISBNS and different file naming conventions. You could rename several hundred figure files by hand, try to use the Windows ren command at the Command Prompt (but don’t–it’s buggy and doesn’t work if you need to lengthen a file name), or get a software tool like Bulk Rename Utility. It sports an irredeemably ugly user interface, but it works great.
    * A figure processer. This is useful if you need to add borders, change formats, or do any other sort of “batch” figure processing work. I like FastStone Photo Resizer. But if you need to crop figures in batches, you probably need something else. (For example, I wrote an Excel book that uses screen captures of the Excel worksheet area rather than the whole Excel window. To crop out the window frame and ribbon, I used Batch Image Resizer, which is a clunky, poorly designed program–but unlike dozens of other figure resizers I looked at, it supports cropping at all edges using fixed pixel measurements. In that project, it was invaluable.)
    * A code converter. Instant VB is pure gold if you need to convert a snippet of code (or an entire project) from C# to VB. Sure, it can’t handle the thorniest LINQ expressions, and the converted code may need some cleaning up to observe all the conventions VB programmers expect, but it does most of the work.

    Tip #2 – Revise as several different people.
    Writers rely heavily on the Track Changes feature in Word, particularly when doing revisions. Sometimes, it’s important to distinguish the changes the same person has made at different stages. (For example, you may want to tell the difference between the initial edits you’ve made to a second edition book, and the changes you made after that to respond to tech review comments.) To make this work, you need to change your Word identity before you start making the new round of changes. You can do this using the General section of the Word Options dialog box. For example, I change my user initials from “mm” to “mm2”.

    Tip #3 – Put everything in the sample code.
    Sooner or later, you’ll need to run an example again, perhaps to correct an error, take a new screen capture, update it to use a new version of your programming framework, and so on. It’s always easier if you’ve left complete code examples behind to work with, otherwise you’ll be forced to recreate your previous work.

    Tip #4 – Make it better, not perfect.
    Perfect is impossible, and if that’s your goal when revising a book, you could spend all day rearranging sentences with little to show for it. Instead, focus on taking the content that’s already there and enhancing it. I’m a bit of a perfectionist, and the thought that an improved edition of a decent book is still a decent book has kept me sane during many a revision.

    Tip #5 – Keep a list of revision search terms.
    When revising a book, I keep a text document with a list of search terms that can help me hunt down sections that need to be changed. Possible keywords include dates (“2005”), software versions (“.NET 3.5”, “Visual Studio 2008”), references to chapters that have moved, links that might no longer be valid (“http://”), and so on.

    Tip #6 – Don’t write two versions of your code.
    At Apress, we do several books in VB and C# editions. Some writers handle this by writing one edition, and then “translating” it to the other language. It’s a thankless, time-consuming task that needs to be repeated for every new software release. Some details (for example, the different capitalization of keywords, the proper use of analogous terms like MustInherit and abstract, etc.), are easy to miss. And as you can imagine, when mistakes get fixed or new content gets added, these copies aren’t in sync, which causes endless headaches. It’s the word processing equivalent of copying raw code from one application to another.
    A far better solution is to create a master copy that has both versions, and then split it into VB- and C#- specific copies at the end. This is a bit tricky in Word, which lacks a conditional text feature, but you can develop a fairly automated solution using Word highlighting and macros, which is what I do.

    Of course, none of these tips addresses the main challenges of writing a book–determining what reader needs to know, what order offers the best presentation, how to warn them about pitfalls, how to find that one little bit of advice they need to get that magic moment of insight, and so on. But these little conveniences just might keep the author from going crazy in the meantime.

    Matthew MacDonald

    • So, Matthew:
      I am waiting for your forthcoming book, Pro Silverlight 4 in VB. And according to Apress, I’m going to be waiting forever!

      Are you going to at least provide the code samples in VB.NET. I could live with that, I suppose….

      • There will definitely be code samples in VB, along with an entire “Pro Silverlight 4 in VB” edition, released at roughly the same time as the C# book (maybe a few weeks later). In fact, the files are finalized and queued up for production as I write this. Unfortunately it’s ahead of the publication information and the book still isn’t listed on Amazon or the Apress site.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s