Dear Abbey: "I Want to Write a Technology Book"

August 15, 2013

Tags: MySQL, Technical Track, Metadata

On September 27 2013, Oracle Database 12c: Install, Configure & Maintain Like a Professional from Oracle Press is hitting the streets. This is the work of four seasoned Oracle database authors including yours truly. With contributing author work having been handled by Marc Fielding, Fahd Mirza, and Michael McKee, this brings to four the number of Pythian people responsible for this work, a follow-up to these successful works in the same series:

Oracle: A Beginner's Guide
Oracle8: A Beginner's Guide
Oracle8i: A Beginner's Guide
Oracle9i: A Beginner's Guide
Oracle Database 10g: A Beginner's Guide
Oracle Database 11g: A Beginner's Guide

It was mid-1994 when I received a panic email from a colleague who was working on the original work in the Oracle Press series - Tuning Oracle. He and another tech in Massachusetts were feverishly trying to meet the September 15 deadline set by Osborne McGraw-Hill, the name of the publisher in Berkeley California in those days. It is so easy to get bogged down writing an essay, not to mention a book of 300-400 pages. The following material in this post will offer 10 tips to start writing. The satisfaction for a job well done (and finished!) may be the ultimate reward from stepping into writing-land.

Tip #1

One of the major hurdles with writing (anything) is to have the words flow well and systematically follow a well-thought out plan. A fundamental problem is the little room for perfectionism, a trait that so many of us share. If one is not careful, writing a book for Oracle Press resembles the following pseudo-code:

START:
 IF text is well worded and flows THEN
  move on to next topic/section
 ELSE
  re-write/re-word the piece of text
 END IF
 goto START

Here is the fix for this quandary ... if you can answer "YES" to at least three of the following five questions, it's fine. Time to move on:

Spelling checked out OK?
Have fundamental grammar constructs been adhered to?
Have acronyms, if the first time used in the chapter, been expanded to their long form?
Has attention been paid to consistent capitalization dictated by the book's style guide?
Have basic formatting expectations been met, such as uniform sections and chapters?

Why only five questions you say? If there were more, you'd get so bogged down you would never finish anything.

Tip #2

You do not need a publisher in this 2013-Internet-this and Internet-that. Just check in with a colleague of mine, Subhajit das Chaudhuri and his two electronic works Integrating Oracle Internet Directory 11.1.1.6 with Microsoft Active Directory 2008 and Oracle Applications E-Business... and Integrating Oracle Applications E-Business Suite 12.1.1 with OID 11.1.1.6 and OAM 11.1.2. So many technical people spend time spinning their wheels trying to figure out how to publish a book and navigate through the book world to get their initiative started. Along come offerings from the giants, of which Amazon's Kindle Direct Publishing may be the most popular.

Tip #3

There is nothing like the good old-fashioned eyeball as an alternative to the electronic spell checker. My experiences have shown me that the spell checker should be used as an assistant NOT a trusted tool in an author's arsenal. You need not go far to see the shortcomings of the spell checker, which just loved the following prose:

It was a far to common occurrence often encountered in the muddle of planning for what wood have bin the initial offering in the sweet of colour full buckets of flours.

Tip #4

The well-worn cliché "beauty is in the eyes of the beholder" is so applicable when writing technical works (and any other type of offerings as a matter of fact). As the author, you may be pleased with the flow, the construct of the sentences used, and the general quality of your written word. Ensure that at least one other set of eyes covers everything you write and offers feedback earlier rather than later.

Tip #5

Perform exhaustive checks on the intra-work cross referencing. There are few turnoffs for the reader bigger than a work where this has not been performed. One of the final passes of the editing phase audits just this phenomenon. Classically, chapter names and numbers change as a book undergoes various stages of completion. There is nothing more frustrating to the consumer (and word gets around!) than a poorly maintained cross-referenced book. Spend your time dreading the following tweet about one of your books:

#OracleTHISandTHAT poorly organized; chapter and diagram references way off base and confusing; #notrecommended

Tip #6

Do not alienate your readers by using local idioms and colloquialisms. Always choose your words and your analogies very carefully. If you live in Chennai and are fluent in a handful of local languages, avoid illustrating some of the points you are making by using jargon and acronyms unique to that part of India. If in doubt, don't. Likewise, if you suspect your primary readership will reside in North America and Europe, pick the context of your analogies very carefully ensuring readers in the Philippines will not be offended by your choice of words.

Tip #7

Use future dates in your code listings. Suppose you had written a work discussing SQL Server 2008, released in August 2008, and a potential buyer saw the following code listing snippet in June 2009:

select created,allowance from invmaster where storeID = 3431
 and created > '2007/11/25' and created < '2007/12/27'

"Hmmm" the reader or potential buyer might say - how current is this work and how much can I trust the advice four years later? Not a big deal, but how about in January 2008 when the book was released, the code snippet stated:

select created,allowance from invmaster where storeID = 3431
 and created > '2012/11/25' and created < '2012/12/27'

Are you lying to your perspective clientele? No, you are marketing to them - a big difference.

Tip #8

Ensure that all your figures and illustrations have slugs - they serve as a guideline to the reader and are especially helpful when a figure resides on page 209 of the book and is referenced in a handful of places further on in the work. There is nothing more frustrating than a figure mention on page 283 that states ...

This concept was discussed then illustrated in Figures 6-12 and 6-13; they offer the best explanation and should be consulted for further details.

The reader then toddles off to chapter 6 and has no idea which of the figures are 12 and 13 without counting the figures from the start of the chapter.

Tip #9

Ensure that no less than two separate persons edit the book start to finish:

A technical person familiar (if not fluent) with the material being covered. That person is representative of a large majority of your target audience.
A non-technical person whose feedback and suggestions will assist flow and assess the feasibility of how you explained a concept and succeeded in getting your points across.

Tip #10

The envelope, please. Guess who your first reader should be... Tada - YOU! This advice relates to those pesky sections of a book that you edit, then re-edit, then re-edit for what seems like an eternity. It is wise to read these portions of your work out loud and tweak the way you say things, the length of your sentences, the words chosen, and above all, the way punctuation has been used. Often I have done just this and before reading a lengthy paragraph and wondered who could have possibly written this gibberish; then when I speak the contents out loud it all comes together into a well-worded section.

Wrap-up

In 1967, The Byrds wrote a very successful song entitled "So You Want to be a Rock'n'Roll Star". Writing technical books is not magic, but there is nothing to replace experience, experience, and experience. I first saw the Oracle software I have come to love and live with in the summer of 1986. It was version 3 running below the line, and I loved it from day one. Since then, I have co-written more than a dozen books for Oracle Press, which were translated into 12 languages. I have given close to 100 presentations at software and other professional gatherings. The best part of my IT career has been mentoring. I started doing that in the mid 1990's and still regard it as one of the biggest rewards of my professional life. Let me leave you with one of the wonders of the many languages we speak - the homonym - it is your right to write, right?

Insight and analysis of technology and business strategy