difference-2023-05-22.tex

\documentclass[10pt,letterpaper]{article}
%DIF LATEXDIFF DIFFERENCE FILE
%DIF DEL manuscript-2023-02-20.tex   Mon May 22 07:42:49 2023
%DIF ADD 11-techbook.tex             Mon May 22 07:42:41 2023

\input{settings}
%DIF PREAMBLE EXTENSION ADDED BY LATEXDIFF
%DIF UNDERLINE PREAMBLE %DIF PREAMBLE
\RequirePackage[normalem]{ulem} %DIF PREAMBLE
\RequirePackage{color}\definecolor{RED}{rgb}{1,0,0}\definecolor{BLUE}{rgb}{0,0,1} %DIF PREAMBLE
\providecommand{\DIFadd}[1]{{\protect\color{blue}\uwave{#1}}} %DIF PREAMBLE
\providecommand{\DIFdel}[1]{{\protect\color{red}\sout{#1}}}                      %DIF PREAMBLE
%DIF SAFE PREAMBLE %DIF PREAMBLE
\providecommand{\DIFaddbegin}{} %DIF PREAMBLE
\providecommand{\DIFaddend}{} %DIF PREAMBLE
\providecommand{\DIFdelbegin}{} %DIF PREAMBLE
\providecommand{\DIFdelend}{} %DIF PREAMBLE
\providecommand{\DIFmodbegin}{} %DIF PREAMBLE
\providecommand{\DIFmodend}{} %DIF PREAMBLE
%DIF FLOATSAFE PREAMBLE %DIF PREAMBLE
\providecommand{\DIFaddFL}[1]{\DIFadd{#1}} %DIF PREAMBLE
\providecommand{\DIFdelFL}[1]{\DIFdel{#1}} %DIF PREAMBLE
\providecommand{\DIFaddbeginFL}{} %DIF PREAMBLE
\providecommand{\DIFaddendFL}{} %DIF PREAMBLE
\providecommand{\DIFdelbeginFL}{} %DIF PREAMBLE
\providecommand{\DIFdelendFL}{} %DIF PREAMBLE
%DIF COLORLISTINGS PREAMBLE %DIF PREAMBLE
\RequirePackage{listings} %DIF PREAMBLE
\RequirePackage{color} %DIF PREAMBLE
\lstdefinelanguage{DIFcode}{ %DIF PREAMBLE
%DIF DIFCODE_UNDERLINE %DIF PREAMBLE
  moredelim=[il][\color{red}\sout]{\%DIF\ <\ }, %DIF PREAMBLE
  moredelim=[il][\color{blue}\uwave]{\%DIF\ >\ } %DIF PREAMBLE
} %DIF PREAMBLE
\lstdefinestyle{DIFverbatimstyle}{ %DIF PREAMBLE
	language=DIFcode, %DIF PREAMBLE
	basicstyle=\ttfamily, %DIF PREAMBLE
	columns=fullflexible, %DIF PREAMBLE
	keepspaces=true %DIF PREAMBLE
} %DIF PREAMBLE
\lstnewenvironment{DIFverbatim}{\lstset{style=DIFverbatimstyle}}{} %DIF PREAMBLE
\lstnewenvironment{DIFverbatim*}{\lstset{style=DIFverbatimstyle,showspaces=true}}{} %DIF PREAMBLE
%DIF END PREAMBLE EXTENSION ADDED BY LATEXDIFF

\begin{document}
\vspace*{0.2in}

\begin{flushleft}
{\Large
\textbf\newline{Ten Simple Rules for Writing a Technical Book}
}
\newline
\\
{Jess Haberman}\textsuperscript{1},
{Greg Wilson}\textsuperscript{2*}
\\
\bigskip
\textbf{1} Anaconda Inc., Austin, Texas, United States, 0000-0002-3779-1999\\
\textbf{2} Third Bit, Toronto, Ontario, Canada, 0000-0001-8659-8979\\
\textbf{*} gvwilson@third-bit.com.
\end{flushleft}

\section*{Introduction}

The Internet has put a world of \DIFaddbegin \DIFadd{technical }\DIFaddend information just a click
away, but that information is often fragmentary, contradictory,
incomplete, or out of date. People \DIFaddbegin \DIFadd{working in science and technology
}\DIFaddend still need coherent narratives that provide \DIFdelbegin \DIFdel{a
coherent overview }\DIFdelend \DIFaddbegin \DIFadd{an overview of a subject
}\DIFaddend and lay out a learning path\DIFdelbegin \DIFdel{that will get them
there}\DIFdelend . In other words, they still need \DIFdelbegin \DIFdel{book-length expositions,
which
means }\DIFdelend \DIFaddbegin \DIFadd{books,
and whether they are printed or digital, }\DIFaddend someone has to write them and
publish them.

One of us (Haberman) has been helping writers and experts produce
instructional content for most of her career: prior to becoming Director
of Learning Solutions at Anaconda, she spent 14 years in book
publishing, with several years at O'Reilly Media \DIFdelbegin \DIFdel{signing and
}\DIFdelend developing technical
books. The other (Wilson) has written four books on
programming, co-authored three others, and edited six. The tips below
summarize what we've learned along the way \DIFaddbegin \DIFadd{about writing books that
teach people technical subjects}\DIFaddend .

\section*{Rule 1: Don't write for money.}

The first thing any prospective author needs to understand is the
economics of publishing. Typically, one-third of the books on a
publisher's list lose money, one-third break even, and one-third are
profitable to a greater or lesser extent. For most, it's ``lesser'':
publishers actually make most of their revenue from a handful of
bestsellers.

For a technical book, your publisher will typically give you royalties
ranging from 10\% to 15\% of net revenue (i.e., revenue after
discounts). You can expect to sell \DIFdelbegin \DIFdel{200–2000 }\DIFdelend \DIFaddbegin \DIFadd{200--2000 }\DIFaddend copies; a handful of books
do much better than that each year, but only a handful. Downloading has
obviously impact this: PDFs and BitTorrent files often appear online
within hours of the first digital sales of books (particularly
textbooks). Assuming a US\$50 price tag, this means that you will
probably earn between US\$500 and US\$7500. Since it's going to take at
least a thousand hours to write the book, you'll almost certainly be
better off financially doing some consulting (or even getting a
part-time job in a fast food restaurant).

You can earn much higher royalties by self-publishing, but doing so
comes with many tradeoffs. You won't have access to the expertise of a
publisher when it comes to layout and design, cover art, several levels
of editing (development, copyediting, proofreading), printing, print and
digital distribution, marketing, and sales. You must dedicate time,
money, and energy to finding partners for these tasks or handle them
yourself, so choose your path wisely.

So why write a book?

\begin{itemize}
\item
  \textbf{To build your reputation.} Many musicians now view albums as a
  way to get people to buy concert tickets and t-shirts. Similarly, many
  authors and publishers view books as a way to get people to enrol in
  tie-in workshops and speaking engagements.
\item
  \DIFdelbegin \textbf{\DIFdel{To give back to the community.}}  %DIFAUXCMD
\DIFdel{None of us got here without
  help, and we have a moral obligation to repay that by helping
  others.
}%DIFDELCMD < \item
\item%DIFAUXCMD
%DIFDELCMD <   %%%
\DIFdelend \textbf{Because you enjoy doing it.} Some people like working with
  wood or wool; you might like working with words.
\item
  \textbf{To gain a deeper understanding of the topic.} Writing requires
  research, and you'll gain expertise during the writing process.
\DIFaddbegin \item
  \textbf{\DIFadd{To make the world a slightly better place.}} \DIFadd{None of us got
  here without help, and the best way to thank the people who taught us
  is to teach others.
}\DIFaddend \end{itemize}

\section*{Rule 2: Read, then write.}

Go through two or three of your favorite technical books and make
notes about what their authors have done well\DIFaddbegin \DIFadd{, such as their use of
analogies, how they use diagrams, how much code they show between
chunks of prose, and so on}\DIFaddend . Doing this will give you some ideas for
your own book, but it will also help you become more conscious of your
\DIFdelbegin \DIFdel{writing—in }\DIFdelend \DIFaddbegin \DIFadd{writing---in }\DIFaddend musical terms, it will help you learn how to listen to
yourself while you're playing. One of us (Wilson) learned a lot from
the classic Unix books by Kernighan et al
\cite{Ke1979,Ke1981,Ke1983,Ke1988} and from \cite{Ud1999}, but your
tastes may vary.

Reading first will also help you understand what knowledge is already
public or well understood, which will help make your arguments even
stronger.

\section*{Rule 3: Test your material.}

Writing a book is a big undertaking, and it's easy to get discouraged.
Instead of tackling it head-on, start blogging regularly (e.g., one
article a week, each a few hundred to a thousand words long). Don't try
to write them in the order you think they'll eventually go into the
book: one reason to blog is to get a better idea of what should come
before what. As you become more comfortable, though, try writing
multi-post series that can eventually become chapters.

If you run even a single workshop based on the material for your book
while you are writing it, you will almost certainly realize that several
of your core assumptions about your audience and material are completely
wrong \emph{while you still have time and energy to fix things}.
Conferences are always looking for tutorials, your local college or
university might be looking for a sessional course, and dozens of
learning sites exist to publish training materials (though in this case
you must be careful that their licensing allows you to re-use the
material). Your colleagues will probably welcome some lunch \& learn
sessions, and if all else fails, you can create a YouTube channel to
find out how your material sounds.

A corollary is that there's no point trying material out if you don't
\textbf{incorporate what you learn}. If you pay attention to feedback,
you will probably rewrite every line of your book at least twice and
revise some parts a dozen times or more. You can skip this work if you
don't collect or act on feedback, but your book will almost certainly be
a lot worse for it.

We recommend that you drywall and then paint, i.e., that you write a
rough draft with placeholders and \emph{then} worry about diagrams,
bibliography citations, glossary entries, and so on. For example, the
word \texttt{FIXME} appeared over a hundred times in first ``complete''
draft of \cite{Wi2019}; half of those turned out to be irrelevant by the
time the text settled down.

An important special case of this is that you should do diagrams on a
whiteboard first. It's faster and more flexible than any computer
drawing tool (even fingertip sketching apps for tablets) and a photo
taken with a cell phone is good enough for your first readers. Many
publishers will re-create your sketches anyway, so don't fuss over them
too much.

\begin{mdframed}
\textbf{Union and Intersection}

\noindent
No matter how carefully you plan, you will hit part 5 and realize that
there was something you should have explained back in part 3. You can
fill this in on the fly if you are teaching in person, but that doesn't
work in a book. For this reason, a live lesson should be the
\emph{intersection} of what audience members don't know (i.e., the
things you're sure they all need) while a book has to be the
\emph{union} of what readers don't know (i.e., the things any of them
need).
\end{mdframed}

\section*{Rule 4: Start with a learner persona.}

A \emph{learner persona} is a fictional character that captures key
aspects of who you are trying to teach, what they already know, and what
they want to learn \cite{Wi2019}. Create one or two that are fairly
similar (i.e., a primary and secondary audience) and write for them,
because a book that's meant for everyone is actually useful to no-one.
Imagine what your persona already knows, their career or academic level,
and what challenges they face. Your goal is to build on the former to
offer solutions to the latter.

As you're doing this, keep in mind the difference between a
\emph{novice} (who is trying to build a mental model), a \emph{competent
practitioner} (who has one and wants to fill in gaps in their
knowledge), and an \emph{expert} (who wants higher-level discussion of
tradeoffs and alternatives). Novices need tutorials that help them build
a coherent mental model of the domain; competent practitioners want to
fill in the gaps in their knowledge, and experts are usually interested
in higher-level discussions of patterns, alternatives, and tradeoffs. No
single book can serve all three well.

As a corollary, \textbf{don't write a general introduction to a topic}
unless you're going to be one of the first two or three to market.
Instead, focus on a particular aspect (e.g., ``Python for Web
Scraping'') or a particular audience (e.g., ``R for Librarians''). Your
potential audience may be smaller, but you'll reach a much higher
percentage of that audience, and a focused book is much easier to write.

And please, \textbf{don't write a reference book}: it can never be as
comprehensive or stay as up-to-date as the Internet. \DIFaddbegin \DIFadd{Tutorials fall out
of date too, but if they focus on ideas rather than technical details,
they stay relevant for much longer.
}\DIFaddend 

\section*{Rule 5: \DIFdelbegin \DIFdel{Know your competition}\DIFdelend \DIFaddbegin \DIFadd{Differentiate yourself}\DIFaddend .}

Conduct research to find out what other resources exist for this topic,
keeping in mind they don't have to be books. Where is the audience that
you have already identified learning more about the topic right now?
What can you offer that differs from and improves on that? The most
common weakness in other resources is they are out of date or no longer
accurate, but other times they are poorly organized, not well edited,
lack some unique insight you can bring to the topic, or are trying to be
too general. Every publisher's proposal form will ask about competition;
finding an answer \emph{before} you have written several chapters can
save you a lot of fruitless labor.

Note that some differentiators are not significant enough to be selling
points. For example, you might argue that your book is better because it
has color diagrams while competing titles are black and white. Color
diagrams usually don't make a significant difference in comprehension,
so to an editor, a request for color printing usually equates to more
investment and less profit.

\DIFaddbegin \DIFadd{Study the style and structure of books you like and mimic a style that
works, or tailor the style of your book to match a successful series
from your top-choice publisher.  The world of publishing is smaller
than it was twenty years ago, and the publishers that have survived
have focused on replicable series and formats.  Whether you want a
traditional publisher or you self-publish, don't re-create the wheel.
}

\DIFaddend \section*{Rule 6: Avoid common mistakes.}

\begin{itemize}
\item
  \textbf{Avoid banal advice} (like ``avoid common mistakes'').
  \DIFdelbegin \DIFdel{Few
  things are as frustrating to the reader as sentences }\DIFdelend \DIFaddbegin \DIFadd{Sentences }\DIFaddend like, ``You should carefully consider users' needs,'' \DIFaddbegin \DIFadd{are
  frustrating }\DIFaddend because no sensible person would recommend the opposite.
  If you can't provide a checklist of specific things to
  consider, or a scenario to give the reader insight into how you think
  through that class of problem, you're giving them the intellectual
  equivalent of junk calories.
\item
  \textbf{Don't \DIFdelbegin \DIFdel{be too granular}\DIFdelend \DIFaddbegin \DIFadd{write for today}\DIFaddend .} Don't spend months or years
  writing a book in such specific detail that a new release of software
  makes \DIFaddbegin \DIFadd{all of }\DIFaddend your advice obsolete or simply wrong. Instead, generalize
  and focus on principles that are likely to be long-lived without
  violating the rule about banality. Your goal should be for your book
  to remain relevant for three to five years.
\item
  \textbf{Don't write to cover your ass.} We have read dozens of books
  that start with a short introduction to XYZ. We cannot remember a
  single one that was actually useful. If your audience knows Python,
  they don't need a chapter-length intro to the language, and if they
  don't, one isn't going to help them. Authors usually include those
  short introductions so that they can claim the book is suitable for
  novices when they knew in their hearts it isn't. Remember, it's
  perfectly acceptable to target an audience with more sophisticated
  knowledge than ``none'' or ``basic\DIFdelbegin \DIFdel{''.
}\DIFdelend \DIFaddbegin \DIFadd{.''
}\DIFaddend \item
  \DIFaddbegin \textbf{\DIFadd{Don't copy.}} \DIFadd{Make sure you credit other people (and AI
  tools---more on that below) when you use their work or base your
  work on theirs, especially if you paraphrase or make superficial
  changes to code examples.  Publishers will drop you like a stone if
  you plagiarize, and telling readers where you got your ideas makes
  you more credible and helps them figure out what to read next.
}\item
  \DIFaddend \textbf{Don't try to \DIFaddbegin \DIFadd{``}\DIFaddend write\DIFaddbegin \DIFadd{''}\DIFaddend .} Don't try to sound like an
  expert; instead, lean into the idea that you \emph{are} an expert and
  write in your own voice. You don't convince readers (or publishers)
  you have worthwhile opinions by sounding like what you imagine smart
  people sound like.
\item
  \textbf{Don't try to be funny.} Very few jokes are funny the second
  time you hear them; even fewer can stand a third re-telling unless
  they're very, very dry. On a related note, please don't use
  exclamation \DIFdelbegin \DIFdel{marks: what }\DIFdelend \DIFaddbegin \DIFadd{marks---what }\DIFaddend you're writing probably isn't that
  surprising, and certainly won't be the second time \DIFdelbegin \DIFdel{around.  Most
  }\DIFdelend \DIFaddbegin \DIFadd{around---and
  please be sparing in your use of }\DIFaddend bold, italics, and
  \DIFdelbegin \DIFdel{underline formatting is superfluous}\DIFdelend \DIFaddbegin \DIFadd{underlining}\DIFaddend \footnote{And remember: nobody reads footnotes.}.
\end{itemize}

\DIFaddbegin \begin{mdframed}
\textbf{\DIFadd{AI Writing Tools}}

\noindent
\DIFadd{Seemingly overnight,
generative AI tools and large language models (LLMs) have changed the way we write
by automating a range of writing tasks.
ChatGPT, for example, can help you conquer writer's block, develop an outline,
write an abstract, do competitive research, adjust your tone, or correct your grammar,
and the list is only likely to grow.
We won't attempt to predict how these tools will change writing in the long run
(which currently means "the next twelve months");
for now, you should treat them the same way you would a spellchecker or grammar checker.
}

\DIFadd{But beware of the pitfalls.
AI writing tools frequently hallucinate (i.e., make stuff up)
and they do not cite their sources---that's your job.
Before incorporating their output into your work,
check your prospective publisher's stance on them:
what do they allow,
how do they want your use of these tools acknowledged,
and what extra fact-checking do they require for work generated by machines?
}\end{mdframed}

\DIFaddend \section*{Rule 7: Write a proposal.}

If your goal is to have your book professionally published, write a
proposal before writing the book. You should spend a few weeks on this
and make it as complete and convincing as possible; if nothing else, it
will help you figure out exactly what you're writing about.

When you pitch it to your preferred publishers, do some research to find
the likely editors so you can be sure they see it instead of it winding
up in the slush pile of unsolicited proposals and manuscripts.

\begin{mdframed}
\textbf{Shop Around}

\noindent
Know what your publishing goals are. Do you prefer the style, brand, or
reach of a specific publisher? Are you seeking the top financial offer?
Identify your goals before you begin pitching. Don't feel you have to
send your proposal to one publisher at a time, but if you are shopping
it around, it is common courtesy to let editors know if the proposal has
garnered interest elsewhere. Communicating your goals and timelines can
only help you in navigating the pitch process smoothly and achieve your
publishing goals.
\end{mdframed}

If you have a strong proposal, it should at the very least land you some
time with editors who are knowledgable about the market for the topic.
The best editors will help you hone the proposal by asking good
questions and steering your book in the right direction.

If you receive an offer for publication, negotiate. Let editors know
if you have received or anticipate an offer elsewhere, or if you're
considering self-publishing. There's no harm in seeking the best offer
you can (i.e., the one most aligned with your goals, whatever they
are): even if an offer doesn't improve, you've wasted nothing and can
move forward knowing that others are truly invested in your book and
will help keep you accountable.

\section*{Rule 8: Automate, but proofread.}

This is the \DIFdelbegin \DIFdel{technical author}\DIFdelend \DIFaddbegin \DIFadd{writer}\DIFaddend 's equivalent of ``trust, but verify\DIFdelbegin \DIFdel{''.}\DIFdelend \DIFaddbegin \DIFadd{.''  }\DIFaddend Depending
on the tools you use, you may be able to regenerate all of the
examples in your book with a single command, but you must still
re-read the discussion about those examples every time you make a
change to make sure they haven't fallen out of step. Similarly, it
doesn't matter how well you know your chosen subject: something will
have changed since the last time you looked, and something else will
change in the year or more it takes you to complete your
manuscript. Your publisher will keep track of errata (i.e., printing
errors); it improves longevity of your book if you address them at
regular intervals.

Keep in mind that most people won't read your book linearly: they will
skip some sections or jump ahead to find an answer to a problem they
need to solve right away. You can help them by making liberal use of
cross-references (e.g., ``as covered in Chapter 2'') to help them
navigate \cite{Li2020}. And because page and chapter numbers frequently
change, use chapter titles instead.

Speaking of chapter titles, consider titles that begin with verbs. If
you're writing an instructional book, this will help ensure you're
focused on the task or skill you're trying to teach. (See \cite{Me2022}
for an example.)

\section*{Rule 9: Trust your reviewers and your editor.}

Lots of people will do cursory reviews or give your manuscript a single
careful read; people who will look at changes over and over again and
see what's actually on the page each time are worth their weight in
rubies. \emph{Trust them}: if a passage doesn't make sense to them, then
it doesn't matter if it makes sense to you. Find a colleague or friend
who you can trust to be brutally honest. It's one thing to get feedback
from your editor or outside reviewers, but someone you trust who will
challenge your arguments is invaluable.

Similarly, as Tom Wilkie once said, an author's job is to produce the
manure in which an editor grows something worth reading. You may sweat
over an example for days, but your audience doesn't see your effort:
they see your results. If explanations that seem clear, concise, and
elegant to you don't make sense to your readers, then they're right and
you're wrong.

A professional editor doesn't get paid extra for making more edits. So
if they mark something, they probably have a good reason. Ask why if
you're not sure. Keep in mind that your motivation and your editor's are
the same, to make the book the best it can possibly be.

Don't be afraid to set it aside. One of us (Wilson) wrote three quarters
of an introduction to R for Python programmers that will probably never
see the light of day. This is not unusual: many authors find that the
more they write, the less they believe the book will actually help its
intended audience. There is nothing to be ashamed of in this: scientists
don't expect every hypothesis to turn out to be true, and authors
shouldn't either.

Of course, if you have signed a contract and are suddenly rethinking
whether your book should exist, have an honest conversation with your
editor about next steps. Don't hide information, and don't become
impossible to reach. Editors are used to authors becoming discouraged
and can provide a much-needed reality check. They can also help you
evolve the reasoning, scope, timing, or approach to your book: it's
actually part of their job to do so.

\section*{Rule 10: Stop, ship, and celebrate.}

Your book will never be perfect. It will probably never even feel
\emph{finished}, any more than software does, but you should ship it
anyway and then celebrate what you've accomplished. Writing a book can
be a slog, but it's not easy to replicate the feeling of accomplishment
when you find your book listed online or receive a shipment of printed
copies. Don't be afraid to tell your friends or post on your social
media accounts: it isn't bragging if you actually did it, and if it was
worth your time to write the book, it's worth your time to help people
find it.

\bibliographystyle{unsrt}
\bibliography{11-techbook}

\end{document}