Writing a Technical Book

Writing a Technical BookI am often asked for more information about writing a technical book. As author or co-author of twelve books focused or touching on technology, I consider myself experienced – not an expert.

I’ve noticed “ah-ha” moments recently when sharing insights and advice, so I thought I’d write a post about it. I hope that’s ok. If you’re here, I reckon it is.

A Typical Workflow for Writing a Technical Book

“So just how does a technical book get written, Andy?” I’m glad you asked. The answer is, unsurprisingly, “It depends.” It depends on the publisher and author(s), but mostly on the publisher. It can also depend on the topic and competition (real or imagined).

Step 0 – Idea

Someone has to come up with an idea for a book. It can be either a publisher or author, but someone says, “There should be a book about that!” Publishers often seek authors these days. Every time I share this fact I get blank stares and looks that communicate, “What did you just say?” It’s true. These days publishers are looking for authors to write about technology topics.

Finding good writers is hard for publishers. The writing process is hard work and requires discipline and stubbornness from authors. I am not making any of this up.

Once the idea for writing a technical book is codified-enough, the next step is…

Step 1 – Proposal

Every publisher with whom I’ve worked has a book proposal process. Book proposal templates vary but share some important features, such as:

  • Title
  • Description
  • Author(s)
    • Author bio(s)
  • Target audience
    • Reader market size
  • Competing titles
  • Projected page count
  • Writing schedule
  • Remuneration details

Most of these items are self-explanatory. Some are negotiable. For example, you will be guessing (wildly) at the reader market size. You will also be guessing page count. And writing schedule.

Although it’s very important I choose to hold off sharing details about remuneration, for now.

When writing a technical book, there is often some give-and-take regarding the book proposal, followed by…

Step 2 – Contract

The book contract usually includes snippets from the proposal. At its heart, the contract is the work-for-remuneration document.

You should always read the contract carefully and strive to understand not only the language of what is written but the nuance of what is not written.

If you have any concerns, I recommend you consult a lawyer – especially if this is your very first experience with a writing contract.

The contract will always include the writing schedule and page count. Pro tip: delivering a first draft early that is longer than the proposed page count is not going to be an issue. (That last sentence is pregnant…)

As an author, you want to make sure you are comfortable with the contract when writing a technical book.

Step 3 – Writing

The author writes (or authors write) the first draft. For technical books, this includes screen shots and code snippets. Writing may also include quotes from others or other books.

Everything must either be original or attributed. No excuses.

There will be language regarding original / attributed content included in the contract, accompanied by language about penalties should the book contain non-original-and-unattributed content, i.e. plagiarized material.

Writing a technical book takes time to do well.

Step 4 – Editing

Editing involves at least a couple phases:

  1. Language editing – someone who is good at human language syntax, plow, and structure and understands technology well-enough to not bungle the author’s intent reads through the manuscript and notes places where better sentence structure, different words, and entire sections can be moved or changed to enhance idea-flow.
  2. Technical editing – someone, usually a technologist, who is willing to walk through the examples, samples, and demo code to verify it works and there are no missing steps.

Sometimes you can find a technologist who is good-enough with language to perform both functions – or a language editor willing to tackle the technology demos – but that’s rare.

Editing takes time to do well when writing a technical book.

Step 5 – Typesetting

Not all books are published physically, but all books pass through a typesetting phase. You may think, “Why, Andy?” That’s a fair question, especially for books published only in electronic formats (e-books).

Formatting the written word is important. There’s an entire science dedicated to fonts. What looks good on a paper page may not be as easy to read in a web browser or an e-reader like the Kindle. Publishers (and authors… well, good authors) want the reader to enjoy as little resistance to reading as possible. That’s not as easy as it sounds.

Books are more than just words. There are images and code to consider. Readers often complain about line-breaks in published code. In response, publishers go to great lengths to manage code line breaks and line continuation indicators. Again, this is not as easy as it sounds.

When writing a technical book, typesetting takes time to do well.

Step 6 – Publication

Once the idea for the book has been conceived, the proposal submitted and accepted, the contract agreed upon, the book has been written, has been edited, and the typesetting is complete; the book is ready to be published.

All authors understand this step: this is why they signed up to write a book in the first place!

There is no way to adequately and accurately communicate the emotions of opening a package and seeing your name printed on the cover of a book.

Conclusion

This post covers writing a technical book at a high-level. In my next post, I share tweaks to this process I have learned from experience.

Andy Leonard

andyleonard.blog

Christian, husband, dad, grandpa, Data Philosopher, Data Engineer, Azure Data Factory, SSIS guy, and farmer. I was cloud before cloud was cool. :{>

4 thoughts on “Writing a Technical Book

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.