Writing a Technical Book

Posted Saturday, April 17th, 2021 

writing

I was inspired to write this post after reading a similar post called How to Write a Technical Book by SerHack. Not because there is something wrong with their post, but because I’d like to focus a bit more on what are your options, and also show how I like to work.

During the last ten years, I have published six technical books about programming. Most of them are self-published works but I recently published Roguelike Development With JavaScript with Apress which is a traditional publisher famous for its programming books. My first popular book was Quick Guide for FirefoxOS Programming published a long time ago. I really like that it got featured in the Leanpub bestseller at the time, it made me really proud. Besides that, I’ve spent the last sixteen years working for a major publisher of Hindu Literature in English.

The reason behind telling you all this, is because my comprehension about book writing has changed and evolved over time, and what I think is the best way to write a book today is not necessarily the same as my own choices in the past. Basically, I don’t want you to repeat my own mistakes.

Let’s break down the publishing process into three broadly-scoped phases:

• preparation: in which you plan and prepare your dream book. This plan will fail.
• writing: this covers both writing and editing.
• publishing: the hardest part actually, publishing and marketing your book.

Every book project will need to go through all of those phases, and the most important phase, the one that will actually cause your book to fail if mismanaged is the third one. People often overlook how important marketing and having a launch strategy is for a book. Pressing publish and thinking that readers will simply flock to your book is a myth. The other two steps can be fixed while you’re working on them, and even if they’re not perfect, your book might still be successful. Let’s dive a bit deeper.

Preparation

The first important decision you need to make is how much involvement you want with your book project, because if you allow it, a book project will swallow all your free time from the day you start it up to the final heat death of the universe. A book might just be a hobby project, or, it might be your job.

How much time you have to spend on it dictates how long it will take to launch it. An important aspect of a book project are the tools and workflows you’re using to produce the book. There are turn-key solutions out there that require very little effort to use, opting for such tools will free up time for you to focus on the other phases such as writing itself, on the other hand, choosing more complex tools and workflows will increase the amount of control and agency you have over your project but will add friction and consume more of your time budget.

I will explore more about these workflows on the section about _writing_, but the decision on which workflow to use should come as early as possible, preferably before you start actually writing the book.

A good outline is worth gold

Your outline is the first step towards organising your mind. The most important part of an outline is not what is in it but what you leave out of it. Books, if left to their own devices, will attempt to grow to wikipedia-size amount of content. You need to constrain your project to something you can actually conclude and that still makes sense for your audience.

The way I like to do an outline is to frame the book in terms of the Hero’s Journey. Your reader is undergoing a journey in which you’re nothing but a facilitator. You’re not there to teach them, you’re there to provide the tools necessary for them to learn by themselves. As the book progresses, the reader is presented with concepts of increased complexity. Throughout the book, these concepts need to coalesce into sample projects built by the user to cement their understanding.

This means that the reader is not necessarily building a single big project in the book, but several small ones. They may compose together into a larger project, but they should be discreet enough for the reader to experiment with them as they read the book and not only when they finish it. The samples are not in service of the book, the book is in service of the samples. The samples are built so the user progress in their learning journey.

By reasoning about your book in this way, you will naturally create a project in which the reader is the centre of attention. It is all about their journey. This keeps the book interesting, and avoids one of the most important pitfalls in my own experience which is writing a book that reads like a dictionary or an encyclopaedia. I find those kind of books useful as references, but they don’t usually make for a pleasant reading experience when you attempt to read them from front to back.

My outlines are chapter based. I will write the chapter tentative title and a bullet list of all that the reader should learn in that chapter. The chapters will be organised so that all the content is written to answer a need of the reader. The answer to that need might be in the form of new concepts, or new applications of a concept that was previously seen.

For many chapters in the Roguelike Development book the reader is building a dungeon-crawl game with a fixed dungeon layout. To progress in their journey to understand the basics of roguelike development, they need to learn more about dungeon generation. A whole new sample is built just to teach basic dungeon generation using BSPTrees; The chapter is written to present these concepts but it is the reader’s act of implementing the sample that actually unlocks the learning experience. The following chapter is a new application of the previous concept, the BSP-based generator is used to create multi-level dungeons. It is a journey of understanding through tinkering with code.

It is important to understand that the outline is not written in stone and that as you write your book, you’re allowed to revise it and radically change it if you realise that it doesn’t actually work.

Samples before writing

It is important to develop your samples alongside your outline. Unless you’re super confident in your mental abilities to hold everything in your mind as you plan your book, you will benefit from a practical hands-on approach during this phase.

If each chapter will include a sample, then build them all now as you write the outline. This will help you debug your own outline by surfacing problems with your plan early before you’ve commit too many words to the draft.

Once your outline and samples are good enough for you, it is time to move on to drafting.

Writing and Editing

People who have never written a book tend to think that writing is the hard part. It is not. It is the easy part. Creating your first draft of a technical book is easy. The hard part is editing and revising it so that your draft becomes something that is good enough to share.

If your outline has been through the initial debugging that happens by building all the samples, and everything is fine with both the plan and the samples, then writing will should feel like a natural consequence of your plan. There should be little friction as all decisions about what goes into each chapter have already been made, it just time to write the content (I know, easier said than done, but easier than many think).

This is also where you need to decide on a workflow, and just like anything in the tech world, there are too many options and it is impossible to recommend the perfect solution. These are some of the things you need to decide about:

Traditional publishing or Self-publishing

Many people think that self-publishing is the last option that an author should choose. That it only happens after they’ve been rejected by too many publishers, that they give up and self-publish. This could not be further from the truth. Many authors, me included, will consider self-publishing first and only go the traditional route if they can find a really good reason.

The discussion about this decision is too complex for me to tackle in a simple subsection, so for now let me do a simple bullet list of pros and cons for each.

Self-publishing

• PRO: You get more money per unit sold.
• PRO: You have full control over editorial decision.
• PRO: You have full control over all the process really.
• CON: You have full control over all the process really.
• CON: You need to do everything yourself, or hire people to do it.
• CON: It is harder to get your book into bookshops.

Traditional publishing

• PRO: You have a team working with you (on good publishers).
• PRO: You have professional editors looking over your draft.
• PRO: You don’t need to worry about the publishing part of the process.
• CON: Publishing and marketing tend to be black boxes, you’re not privvy to the plans.
• CON: Getting the book into bookshops still hard as most publishers are POD for books that are not from really famous authors in the tech field, you still can probably order the book from a bookshop, but they might not carry stock in the shop.

If you choose to go with traditional publishing, this is where you need to stop and start reaching out to publishers. Some cool ones in the computer programming ecosystem are The Pragmatic Programmers, No Starch, Apress, Pakt, Manning.

You should find who is the acquisition editor for the area that you want to publish in is in the publisher’s you want to work with. A good way to do it is to pick competitor books and look at their frontmatter to see who the editors were. They are usually a LinkedIn or Twitter message away from you. Reach out to them with a pitch. If they like it, they will tell you how their proposal process work. You will need to adapt your outline to whatever that publisher needs, and then follow their workflow.

Going through the self-publishing route provides you with much more option. I can’t go over all the options available much like a web developer can’t list all the possible ways to create a web app. What I can tell you is that there are some really easy ways to do it, and some others that are more involved.

Self-publishing, the easy way

In my own personal and very subjective view, the easiest way to self-publish a book is through Leanpub, which is a SaaS platform that will not only provide you with the tools and workflows to write a book, but also provide you with the means to sell it with their own store handling all the logistics and payment. Your first 100 books in Leanpub are free but after that you will need to go for one of the paid plans. Depending on your needs it might be worth going with their Pro plan which provides more features such as print-ready PDF export. I’m a Pro user and published four books with them.

Self-publishing, the new easy way

A new lets-serve-all-your-author-needs solution that is growing a lot in my heart is Reedsy. They provide a marketplace to help you meet all kinds of professionals you need—editors, copyeditors, marketeers, cover designers, beta readers, etc—but they also have a kick ass online editor for you to write your book. You can use their platform to write the book, hire the professionals listed there to work on the book, and from the same platform generate the eBooks and ready-to-print PDFs.

Also, they have a wonderful YouTube Channel and blog, with a ton of content about creative writing. Their platform is more geared towards non-technical books, but can still be used to create them.

To be honest, I haven’t covered half of all they offer. Just check their page. They’re awesome.

Self-publishing, the desktop apps way

Do you prefer to work with desktop apps? Me too. So, the darling of the industry is an app called Scrivener. It is worth every penny. If you’re not going to remember anything from this (very extensive) blog post, remember this: Scrivener is worth gold.

I can’t stress how good Scrivener is for your writing career. It is worth buying a license, and devoting time to master it. You will be able to use it throughout the years and it will become your faithful squire, always ready to lay a helping hand in your journey.

You can use it to manage your outline, your research, write your draft, do all the revisions, and then generate eBooks and pdfs.

If you want even prettier eBooks, then combine Scrivener with another app called Vellum, and you’re good to go. Vellum is mac-only though.

My latest book: Development Oriented Development was planned, organised, written, and assembled with Scrivener.

Self-publishing, the FOSS way

Yeah, I bet the FOSS readers among you were already getting nervous with all the proprietary software listed above, right? Well, there are many FOSS options. You can go with novelWriter which is a tool that I’ve discovered recently, and haven’t yet used, but that seems quite promising.

It reminds me of Scrivener, but with the advantage of markdown, I’m keen to try it out some day. Unfortunately, it doesn’t appear to generate proper eBooks.

The swiss-army knife of book publishing in the FOSS world is Pandoc, which is actually used behind the scene by many desktop apps and SaaS. It is an extremelly flexible and powerful tool. Mastering it will take a while and might be beyond what you’re willing to do, but it is worth it.

Another important app is Scribus which is actually a Desktop Publishing app like Adobe InDesign and Affinity Publisher. You can use it to layout a book that you’ve written elsewhere, but it has a steep learning curve compared to all the softwares listed in this article.

Drafting and Editing

Once you have decided on the tool you’re using, it is time to draft. Your manuscript is the content of your book before it goes through layout and typesetting. You will evolve the manuscript by creating multiple revisions of it. Your first draft will go to an editor, who will return it to you after their initial pass is done. You will repeat this ping pong with editors, copyeditors, technical reviewers, and artists, until all the stakeholders are happy enough.

The first draft sometimes resembles the final book very little, in other times the editor is basically fixing just some little grammar mistakes. This depends not only on your draft, but also on your editor. Some publishers might be understaffed and their editors don’t have enough time to invest in your project, you might be self-publishing and paid just for simple copy editing instead of developmental editing.

It is important to realise that this initial draft is not your final product. It needs to go through revision, and that the revision objectives are beyond just fixing grammar and typos. You might need to refactor much more. That is when alpha readers become very valuable. Give the book to trusted readers and let them help you figure out what needs changing. If you’re into FOSS, develop the book in the open and let contributors help you all the way.

By the end of this process, you should have eBooks and maybe ready-to-print PDFs.

Publishing and Marketing

Oh boy, I’m shooting myself on the foot here. It is impossible to cover all that one needs to know in just a section of a blog post. Let me first plug an online course: The Self-Publishing formula. They have many courses, a podcast, and a community that covers all you might need to know to make your book a success after you have actually written the book. It is not cheap, but it will cover so much content. It will teach you so much stuff. If you counted the hours you’d spend to research and learn all that on your own, you’d end up spend more time and money than actually paying for the course. I’m a happy student there. Be aware that the course is focused on fiction and not technical publishing, but that the methods and tools presented there work just as well for tech books.

It is important to have a marketing plan. Hitting publish is no guarantee of success. Readers won’t magically appear unless you have a large following already. Heck, maybe you’re Evan You writing a book about Vue.js, when you hit publish, readers will definitely flock to your book. Heck, I’d buy your book. But for most authors, having a marketing plan is a must.

Some things that will really help your book:

• Be active in the communities around your book’s main topic. Active doesn’t mean keep plugging your book, it means be a good citizen in that community and help others without constant upselling.
• Depending on your niche, you will need to pay ads. I don’t have any experience with them, but that course mentioned above does.
• Make it easy for readers to engage with you. Their success will bring a smile to your face.
• If being an author is part of your life, and you can see yourself publishing many more books. Create a mailing list to keep track of your writing. Encourage your readers to sign up with reader magnets.

You need to actively promote your books even if you’re not self-publishing. Traditional publishers will put too many books out every year and they will put marketing effort on the big sellers only. You need to help sell your books, no one will do it for you (unless you hire someone to do it of course, go see Reedsy).

Anyway, this has been a gigantic blog post. Kinda of a brain dump. If you want to know more about any aspect of what was written here, feel more than encouraged to reach me over Twitter, Mastodon, or WebMentions. The contacts are below this post.