#[1]Atom Feed
[2]AndreGarzia.Com
[3]Blog [4]About [5]Books
[6]Writing a Technical Book
Posted Saturday, April 17th, 2021
[7]writing
I was inspired to write this post after reading a similar post called
[8]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 [9]Roguelike Development With JavaScript with [10]Apress
which is a traditional publisher famous for its programming books. My
first popular book was [11]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.
I love this cover... I love this cover...
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
[12]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.
Initial brainstorm for my Roguelike Development book. It didn't go as
planned in there... Initial brainstorm for my Roguelike Development
book. It didn’t go as planned in there...
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.
The book ended up with 9 Chapters and 314 pages. The book ended up with
9 Chapters and 314 pages.
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 [13]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 [14]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 [15]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 [16]YouTube Channel and [17]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 [18]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.
I'm writing a RPG book with Scrivener. I’m writing a RPG book with
Scrivener.
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 [19]Vellum, and you’re good to go. Vellum is mac-only
though.
My latest book: [20]Development Oriented Development was planned,
organised, written, and assembled with Scrivener.
Cover for Development Oriented Development eBook Cover for Development
Oriented Development eBook
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 [21]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
[22]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 [23]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: [24]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 [25]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.
Did you enjoyed reading this content? Want to support me?
You can [26]buy me a coffee at ko-fi.
Comments? Questions? Feedback?
You can reach out to me on [27]Twitter, or [28]Mastodon, [29]Secure
Scuttlebutt, or through [30]WebMentions.
Mentions
© 2005-2021, Andre Alves Garzia
☕ If you want to support me, you can [31]buy me a coffee. ☕
💖 This page was generated by Racket 8.1 + Pollen 3.1.2792.636. 💖
Feed is available via [32]Atom. I am also available on [33]Mastodon,
[34]Github, [35]Sourcehut, [36]Secure Scuttlebutt and [37]Twitter.
My photo [38]Andre Alves Garzia André Alves Garzia
Andre is a Mozilla TechSpeaker focused on decentralisation technologies
and is an active member of the Secure Scuttlebutt community. In the
recent years he published books about Firefox OS and managed a Web
Literacy program in vulnerable neighbourhoods of Rio. He is a firm
believer in empowerment through technological experimentation. His now
lives in London with his wife, cats and more IoT boards than he can
ever put into use.
References
1.
https://andregarzia.com/feeds/all.atom.xml
2.
https://andregarzia.com/index.html
3.
https://andregarzia.com/recent.html
4.
https://andregarzia.com/about.html
5.
https://andregarzia.com/books.html
6.
https://andregarzia.com/2021/04/writing-a-technical-book.html
7.
https://andregarzia.com/topics.html#writing
8.
https://serhack.me/articles/how-to-write-technical-book/
9.
https://books2read.com/u/mZeXXe
10.
https://apress.com/
11.
https://leanpub.com/quickguidefirefoxosdevelopment
12.
https://en.wikipedia.org/wiki/Hero's_journey
13.
https://work.chron.com/acquisitions-editor-do-8140.html
14.
https://leanpub.com/
15.
https://reedsy.com/
16.
https://www.youtube.com/channel/UCpo0MkTAyEl73PmIVs8CQvQ
17.
https://blog.reedsy.com/
18.
https://www.literatureandlatte.com/scrivener/overview
19.
https://vellum.pub/
20.
http://andregarzia.com/books/development-oriented-development.html
21.
https://novelwriter.io/
22.
https://pandoc.org/
23.
https://www.scribus.net/
24.
https://selfpublishingformula.com/
25.
https://www.indieauthorplatform.com/what-is-a-reader-magnet-and-why-do-you-need-one/
26.
https://ko-fi.com/andregarzia
27.
https://twitter.com/soapdog
28.
https://toot.cafe/@soapdog
29. ssb:@gaQw6z30GpfsW9k8V5ED4pHrg8zmrqku24zTSAINhRg=.ed25519
30.
https://indieweb.org/webmention
31.
https://ko-fi.com/andregarzia
32.
https://andregarzia.com/feeds/all.atom.xml
33.
https://toot.cafe/@soapdog
34.
https://github.com/soapdog
35.
https://git.sr.ht/~soapdog/
36. ssb:@gaQw6z30GpfsW9k8V5ED4pHrg8zmrqku24zTSAINhRg=.ed25519
37.
https://twitter.com/soapdog
38.
https://andregarzia.com/
