So You Want to Write a Book – Part 2

A few days ago I posted an article on what to consider when you get the crazy idea to write a book. If you are still motivated, then allow me to offer some additional tips and guidance on the mechanics of writing a tech-related book.

Publishing Decisions

The biggest factor in writing your book will be how you intend to publish it. In most situations, you need to reach this decision before writing. You might opt to go with a traditional print publisher like Manning Publications. If so, your publisher will most likely have a firm set of writing guidelines and most likely a template for you to follow. Expect a bit of a learning curve to adjust to their template. Because of their processes, publishers tend to be sticklers when it comes to their templates. Going with a traditional publisher has one major drawback -- time. Traditional publishers have a process that involves a number of editors and steps.  Depending on how fast you can write and the publisher it may take many months for your finished manuscript to hit the virtual book store shelf. In the tech world this is a risky proposition. Back when software and technology ran on longer release cycles, often as much as 3 years, it didn't matter if it took 9 months to get a book published.

However today we seem to see a much faster release cadence. It is not unreasonable to think that by the time your book is published a new version of the thing you wrote about will be released! This is not to say you should skip this publishing route. Your book may be on an introductory topic that is unchanged with new product releases. On the upside, traditional publishers provide services, like copy editing, that you may have to handle on your own.

The other major alternative is to self-publish on a platform like Leanpub.com. In this model, you are responsible for all of the writing mechanics and processes. Leanpub handles the sales. There is definitely more work on your part but on the upside, you tend to get a better royalty payout compared to a traditional publisher. And since sites like Leanpub are essentially digital, it is very easy to update your manuscript and release new versions.

Tools

If you are going to write a book, it stands to reason you need something to write with. If you go with a traditional publisher, most likely they will have a Microsoft Word template. Or at the very least they will have some sort of style guide. If you are self-publishing you likely have more options. Personally, since I publish on Leanpub these days, I create markdown files. There are a few markdown editors, like Markdown Pad 2 and Typora. Or if you are a regular reader of my blog, you are probably a VS Code user which has terrific markdown support. There is even a LeanPub Snippets extension.

You will also need a good screen capture program like Snagit. You need something that can save high resolution graphics in a variety of formats and be able to edit and annotate. More on images later.

Style Guide

If you are self-publishing I strongly recommend you create a style guide for your subject matter. For example, if you are writing a PowerShell related book you might want to write all cmdlet names using their proper casing, such as Get-Service and make the name boldfaced. Perhaps you want to make parameter names italicized. Do you want to include the dash with the parameter name? That's up to you.

I will make a suggestion regarding section headings in your chapter. Write them in title case. Instead of using this: "Write objects to the pipeline", style it as "Write Objects to the Pipeline". You can use a site like https://titlecaseconverter.com/ to make it easier.

If you are referencing product names, be sure to use the proper format. For example, "VMware" and not "VMWare".

Whatever you do, be consistent.

Images

A few words on images and figures. if you are working with a traditional publisher, they will have guidelines regarding format, resolution, sizes and perhaps even naming conventions. LeanPub also has image guidelines. Regardless, if you take a screen shot, I suggest saving the initial capture as a tif or other lossless format in full color. You can then create a copy to meet your book requirements. Poor quality graphics is the fastest way to make your book appear unprofessional.

But just because you can create a high-quality graphic doesn't mean you should. I've seen my share of books with screen shots of console screens that are in essence nothing more than black boxes with some white text. My recommendation is to only use a screen shot or graphic, when the figure is the best or only way to convey the information. If it is a complex figure, like a dialog box, you might need to annotate it and reference the annotations in your text. Your graphic should also focus on the element you are writing about. Don't take a full desktop screen shot when you are only writing about a specific field in a single dialog box. If your illustration doesn't contribute to your story, reconsider it.

As for those console-based examples, since all that matters is the text, consider formatting it as a code sample.

Code Samples

If your book will include code snippets or examples, you should have a template that formats the text, preferably in a fixed width font. If you are recreating a console-based screen, you may want to include the prompt, the command and the output. Don't feel you have to show the entire output. Often you only need a few representative lines. You can insert an ellipses (…) at the end to indicate you've truncated the output.

The trickiest part in formatting code samples, is that you are often fighting a width limitation. In a printed book you may only be able to go 80-90 characters before lines start wrapping. When showing command output, you might need to truncate each line with an ellipses. Maybe even tighten up some column spacing. If you feel the reader will be missing out on too much information, then try a screen capture.

Even though I am guilty of this in previous works, I now am very conscious about what code I show in samples. More than likely you will be able to, and will want, to offer your complete, normalized code samples for download. If you have a 100 line Python script, you probably don't need to include the entire script in your manuscript. Make mention where the full code can be obtained and only include the relevant sections that you need to discuss. A screen shot of your code in Visual Studio doesn't add any value, unless you are taking advantage of graphical annotations.

Write Every Day

My last recommendation is that you need to write every day. Find a time of day where you can work uninterrupted for a few hours. Remove distractions and write. If you've created an effective outline for each chapter where each level is a chapter sub-heading, the book will start writing itself. You need to "fill in the blanks" for each heading.

When you are ready, here's the next article with additional suggestions and recommendations on writing your first book.

---

---