• Have an outline of your material prepared before you contact a publisher, for this will be one of the first things your editor, producer, handler, whatever they're called will ask for.

  Since good books take about a year to produce, do as much as you can before getting a publisher involved, for you'll probably be given six weeks and have to make many changes to your existing manuscript.

• Try to budget your time so that you can let your material sit for a day before you submit it and then review it before you do so. You will be surprised at the number of little things you'll find by taking that break. Your copy will be stronger for it.

  It also helps to read your material aloud before submitting it--even the code. Again, you may be surprised at the things you find.

• Find someone you respect willing to review your copy, for you may or may not be fortunate enough to have a skilled technical reviewer assigned to your work. You may get lucky, but don't count on it.

• Don't expect riches; few technical books succeed well enough to earn enough royalties to make it worthwhile.

  As an example, I was once approached to work on a couple of chapters for a book. The problem was that I had three weeks to write as many chapters. I was fortunate enough to be able to devote all my energies to that project and met those deadline handily, but I wouldn't have been able to had I had a day job at the time. In the end, I was paid $2500 and earned more than the original author did, for roughly 1/10th the work. I don't know the details of the contract that author signed, but it was an interesting observation.

  Mind you, some books do earn good residuals for the authors, many do not--especially those from the "second-tier" publishers.

• If your book involves a GUI, invest in a good screen snapshot utility, for that can be an extremely time-consuming part of the project--especially if you're working with beta software, e.g. a new release.

  Indeed, writing a third-party title for unreleased software is more demanding than writing one for shipping software, for you don't know what the publisher will pull at the last second.

  As an example, one writer I know had invested a good deal of time writing on a feature in a certain database product, submitted it, and was dismayed when the publisher pulled that feature just before release. It was simply too broken to ship. Consequently, their book (which discussed said feature in very glowing terms) ended up being a bit of an embarrassment because it referred to something that didn't exist.

  The main point in that if you are writing on unreleased software, remember that you will have to submit your copy roughly two months before the software goes gold. (Ever wonder why so many initial books suck? That's one reason; people vamp because they don't know what the final keystrokes or screens will look like.)

• Don't be tied to your prose. Your copy editor will almost always have different opinions regarding style and the proper use of the language. they'll ask for changes that might seem trivial to you. Don't fight it--unless you really feel strongly about it. It's rarely worth the time and effort.

  Interestingly, on page 240 (of my edition), The Pragmatic Programmer describes a case where a copy editor wanted to change a "When" to an "If" and the authors resisted (properly, in my opinion). I suspect there were many, many other change that the authors didn't challenge. Carefully call your shots, for your copy editors are as passionate about language as you are about your field of expertise.

• Keep the obscure references to a minimum. You're readers are trying to learn something specific and don't really care about your extensive knowledge of "Star Trek" (unless, of course, you happen to be writing a novel in that mythos...but that's a different form of writing.)

• Gimmicks suck. Don't use (or get involved) with them unless you're very good. Most aren't.

• Write simply. Many good book go into extensive detail and end up extremely difficult to read. Choose your words and your points as carefully as you choose your code. If your readers can't make sense of your material, they'll eventually give up.

• Write about something you really care about, for you may end up being extremely tired of the work before you're done. Maintain your enthusiasm through the entire process, including reviewing the galley sheets and the index. Galleys are extremely tedious to review; do so with care, for typos always happen and only you can prevent them from appearing.

• Don't expect your audience to know as much as you about your subject. You may, for example, have to write some introductory material designed to provide a conceptual framework for understanding your information. This is necessary. In Perl terms, it means that, yes, you may have to say why CGI.pm is a good thing, even though that's been done and done well, repeatedly.

• Similarly, avoid teaching bad habits. Some editors believe you should show how to do things the hard way and then show how to do them the easy way. Personally, I prefer to only see how to do it the easy way. Why waste your readers' time? (Granted, there are times that this is necessary, but I argue that, as a device, it's used far too often. Avoid it, if at all possible.)

• Don't reinvent (or rewrite) the wheel unless you've got a completely new take on it that greatly improves on the original. For example, consider the Gecko book. While I liked it, I read it after reading Llama. As a result, I was more than annoyed when many of the code samples were little more than the original ones with "Randal" changed to "Erik." (Sorry guys, that's a personal thing. It seemed cheap, is all.)

  (Not to say there isn't good, original material in Gecko. But it seemed really weird that the code, in many cases, showed such a minor, cosmetic change. IMHO, If you're gonna' steal the code, leave it alone and attribute it properly. Can't you invest your time in adding to the original material, instead of reshaping to stroke your personal ego?)

  Note: A certain little birdie has previously hinted than the forthcoming edition of Llama has done away with the need for Gecko. I have no details on it, just veiled rumors from a certain source.

• If you want to write a book, be sure you know how to a) read and b) write. That's not as obvious as it seems. Find books you like and then study their construction. Why do you like them? What sets them apart from books you don't like? Learn from those. Learn from the ones you dislike. I'm sure we've all read books that have been poorly written. Don't write another.

To my mind, the best advice comes from meditating on Hamlet's advice to the players in Act III, Scene II:

HAMLET  Speak the speech, I pray you, as I pronounced it to
        you, trippingly on the tongue: but if you mouth it,
        as many of your players do, I had as lief the
        town-crier spoke my lines. Nor do not saw the air
        too much with your hand, thus, but use all gently;
        for in the very torrent, tempest, and, as I may say,
        the whirlwind of passion, you must acquire and beget
        a temperance that may give it smoothness. O, it
        offends me to the soul to hear a robustious
        periwig-pated fellow tear a passion to tatters, to
        very rags, to split the ears of the groundlings, who
        for the most part are capable of nothing but
        inexplicable dumbshows and noise: I would have such
        a fellow whipped for o'erdoing Termagant; it
        out-herods Herod: pray you, avoid it.

First Player    I warrant your honour.

HAMLET  Be not too tame neither, but let your own discretion
        be your tutor: suit the action to the word, the
        word to the action; with this special o'erstep not
        the modesty of nature: for any thing so overdone is
        from the purpose of playing, whose end, both at the
        first and now, was and is, to hold, as 'twere, the
        mirror up to nature; to show virtue her own feature,
        scorn her own image, and the very age and body of
        the time his form and pressure. Now this overdone,
        or come tardy off, though it make the unskilful
        laugh, cannot but make the judicious grieve; the
        censure of the which one must in your allowance
        o'erweigh a whole theatre of others.
[download]

Off topic? No, not really. His advice applies to any enterprise that wishes to effectively entertain, inform, or (essentially) communicate.

--f