PROLOGUE: WHY WRITE TECHNICAL CONTENT ..........................................

1
CHAPTER 0: YOU AND YOUR GUIDE ................................................................... 4
0.1 INTENDED AUDIENCE ...................................................................................................... 4
0.2 ABOUT THIS HANDBOOK ................................................................................................ 6
ACT 1: THE CRAFT.................................................................................................. 10
CHAPTER 1: FINDING AND VALIDATING IDEAS.......................................... 14
1.1 THE 9 QUESTIONS PROCESS .........................................................................................15
1.1.1 Questions .............................................................................................................. 16
1.1.2 Merging Answers .............................................................................................. 20
1.2 IDEA VALIDATION ...........................................................................................................22
1.3 ARTICLE LIFESPAN .........................................................................................................25
//TODO..................................................................................................................................30
THE 9 QUESTIONS PROCESS EXAMPLE ..............................................................................32
CHAPTER 2: PUBLISHERS.................................................................................... 35
2.1 FINDING PUBLISHERS ....................................................................................................37
2.2 PITCHING ..........................................................................................................................39
2.2.1 Finding and Pitching Your Second Publisher ....................................... 40
2.3 WORKING FOR AN AGENCY ...........................................................................................42
//TODO..................................................................................................................................43
CHAPTER 3: RESEARCH........................................................................................ 44
3.1 FINDING SOURCES ..........................................................................................................45
3.2 EVALUATING SOURCES ..................................................................................................47
3.3 INTERVIEWING ................................................................................................................49
3.3.1 Finding the Right Interview Subject ......................................................... 51
3.3.2 Synchronous Interviews ................................................................................. 52
3.3.3 Asynchronous Interviews .............................................................................. 53
3.3.4 What to Ask ......................................................................................................... 54
3.4 CITATION AND RIGHTS ..................................................................................................56
//TODO..................................................................................................................................57
CHAPTER 4: PREPARING TO WRITE ............................................................... 59
4.1 OUTLINES .........................................................................................................................59
4.1.1 Audience ............................................................................................................... 62

i
 4.1.2 Structure............................................................................................................... 64
4.1.3 Contents ................................................................................................................ 67
4.1.4 Cancelling an Article ....................................................................................... 68
4.2 SAMPLE CODE ..................................................................................................................68
//TODO..................................................................................................................................72
CHAPTER 5: WRITING FOR SOFTWARE DEVELOPERS............................. 73
5.1 THE ACTUAL WORDS .....................................................................................................74
5.1.1 Craft and Style.................................................................................................... 75
5.1.2 Voice ....................................................................................................................... 77
5.1.3 Your Writing Practice ..................................................................................... 79
5.1.4 Markdown ............................................................................................................ 81
5.2 GRAPHICS .........................................................................................................................81
5.3 OVERCOMING WRITER’S BLOCK ..................................................................................85
//TODO..................................................................................................................................87
CHAPTER 6: EDITING ............................................................................................ 88
6.1 CONTENT ..........................................................................................................................88
6.1.1 Structural Principles ....................................................................................... 89
6.1.2 Code ........................................................................................................................ 91
6.1.3 Reading Aloud .................................................................................................... 91
6.2 STYLE GUIDES ..................................................................................................................92
6.3 WORKING WITH EDITORS .............................................................................................94
6.4 EDITING FOR SELF-PUBLICATION ...............................................................................96
6.4.1 Beta Readers ....................................................................................................... 96
6.4.2 Professional Proofreading and Copyediting ......................................... 98
6.4.3 Edits over Time .................................................................................................. 98
//TODO..................................................................................................................................99
CHAPTER 7: PUBLISHING ..................................................................................100
7.1 LAST STEPS ................................................................................................................... 101
7.1.1 Skimmability.................................................................................................... 102
7.2 PLATFORMS................................................................................................................... 103
7.2.1 Wordpress ......................................................................................................... 103
7.2.2 Ghost.................................................................................................................... 104
7.2.3 Static Site Generator .................................................................................... 105
7.2.4 Ebooks and PDFs ............................................................................................ 107
7.2.5 Print ..................................................................................................................... 108

ii
 //TODO............................................................................................................................... 108
ACT 2: THE PROCESS IN ACTION ....................................................................109
CHAPTER 8: EXAMPLE TUTORIAL: SCRAPING AND GENERATING
SHAKESPEAREAN SONNETS .............................................................................112
8.1 READER’S NOTES ......................................................................................................... 112
8.1.1 Tutorial Outline .............................................................................................. 112
8.1.2 Writing Concepts ........................................................................................... 114
8.2 COMPLETE TUTORIAL ................................................................................................. 120
SCRAPING AND GENERATING SHAKESPEAREAN SONNETS.......................................... 120
Setting Up..................................................................................................................... 120
English Class in under 200 Words ..................................................................... 121
First Stage: Scraping the Data ............................................................................ 122
Second Stage: Parsing Rhymes ........................................................................... 128
Third Stage: Building Sonnets ............................................................................. 135
In Conclusion .............................................................................................................. 137
CHAPTER 9: EXAMPLE TUTORIAL: PRACTICING JAVASCRIPT WITH A
SHAKESPEAREAN SONNET GENERATOR .....................................................139
9.1 READER’S NOTES ......................................................................................................... 139
9.1.1 Tutorial Outline .............................................................................................. 140
9.1.2 Writing Concepts ........................................................................................... 140
9.2 COMPLETE TUTORIAL ................................................................................................. 143
PRACTICING JAVASCRIPT WITH A SHAKESPEAREAN SONNET GENERATOR ............ 143
Setting Up..................................................................................................................... 143
Data Structure: Arrays in Arrays in Arrays ................................................... 144
Making Random Samples ...................................................................................... 146
Building and Adding a String to the HTML ................................................... 147
Making a Sonnet on a Button Press .................................................................. 148
In Conclusion .............................................................................................................. 149
CHAPTER 10: EXAMPLE ARTICLE: COMPUTATIONAL POETRY..........151
10.1 READER’S NOTES ...................................................................................................... 151
10.1.1 Article Outline............................................................................................... 151
10.1.2 Writing Concepts ......................................................................................... 153
10.2 COMPLETE ARTICLE ................................................................................................. 156
COMPUTATIONAL POETRY ................................................................................................ 156

iii
 Why Poetry? ................................................................................................................ 157
Considering Inputs ................................................................................................... 158
Naive Selection........................................................................................................... 159
Markov Chains ........................................................................................................... 160
Neural Networks ....................................................................................................... 161
In Conclusion .............................................................................................................. 163
Further Reading ........................................................................................................ 163
ACT 3: THE BUSINESS OF WRITING ...............................................................165
CHAPTER 11: PRICING........................................................................................168
11.1 PER ARTICLE .............................................................................................................. 170
11.2 PER WORD ................................................................................................................. 171
11.3 PER HOUR .................................................................................................................. 172
11.4 FREE ............................................................................................................................ 173
//TODO............................................................................................................................... 175
CHAPTER 12: CONTRACTS AND INVOICING ...............................................176
12.1 COMMON CLAUSES IN CONTRACTS........................................................................ 177
12.2 WRITING YOUR OWN LETTERS OF AGREEMENT................................................ 179
12.3 INVOICING ................................................................................................................... 180
12.3.1 Payment Processors ................................................................................... 181
12.3.2 Payment Terms ............................................................................................ 182
//TODO............................................................................................................................... 182
CHAPTER 13: INTELLECTUAL PROPERTY AND PUBLICATION RIGHTS
.....................................................................................................................................184
13.1 PUBLICATION RIGHTS .............................................................................................. 184
13.1.1 Work for Hire ................................................................................................ 185
13.1.2 First Serial ...................................................................................................... 186
13.1.3 Second Serial and Anthology Rights ................................................... 187
13.1.4 Retaining Rights .......................................................................................... 188
13.1.5 Online versus Print ..................................................................................... 188
13.2 SOFTWARE LICENSING ............................................................................................. 188
13.3 ATTRIBUTION ............................................................................................................ 190
//TODO............................................................................................................................... 191
CHAPTER 14: CONTENT MONETIZATION ...................................................192

iv
 14.1 ADVERTISING ............................................................................................................. 193
14.1.1 On the Death of Advertising ................................................................... 195
14.1.2 Affiliate Links ................................................................................................ 197
14.2 SPONSORSHIPS ........................................................................................................... 198
14.3 SALES AND SUBSCRIPTIONS .................................................................................... 200
14.4 CONTENT MARKETING............................................................................................. 202
14.4.1 Indirect Monetization ............................................................................... 204
//TODO............................................................................................................................... 205
CHAPTER 15: PROMOTING YOUR WORK ....................................................207
15.1 PLATFORMS ................................................................................................................ 208
15.1.1 Hacker News ................................................................................................. 209
15.1.2 Reddit ............................................................................................................... 211
15.1.3 LinkedIn .......................................................................................................... 212
15.1.4 Twitter ............................................................................................................. 213
15.1.5 Niche Platforms ........................................................................................... 214
15.2 EMAIL LISTS ............................................................................................................... 214
15.3 IN PERSON .................................................................................................................. 215
15.4 METRICS ..................................................................................................................... 217
15.5 SEARCH ENGINE OPTIMIZATION ............................................................................ 218
//TODO............................................................................................................................... 219
CHAPTER 16: LONG-TERM ENGAGEMENTS................................................220
16.1 BOOKS ......................................................................................................................... 220
16.1.1 Working with Publishers ......................................................................... 221
16.1.2 Self-Publishing.............................................................................................. 222
16.2 SERIES ......................................................................................................................... 222
16.2.1 Columns ........................................................................................................... 224
16.2.2 Courses............................................................................................................. 224
16.3 ALTERNATE FORMATS ............................................................................................. 225
16.3.1 Academic Papers ......................................................................................... 225
16.3.2 Whitepapers and Case Studies .............................................................. 226
16.3.3 Videos ............................................................................................................... 227
16.3.4 Speaking.......................................................................................................... 229
16.4 JOBS.............................................................................................................................. 230
//TODO............................................................................................................................... 232
APPENDICES ...........................................................................................................234

v
APPENDIX A: COMPLETE INTERVIEW TRANSCRIPTS ............................235
COURTLAND ALLEN ............................................................................................................ 235
JEFF ATWOOD ...................................................................................................................... 247
CHRIS ON CODE.................................................................................................................... 259
PETER COOPER .................................................................................................................... 273
ANGEL GUARISMA ............................................................................................................... 287
MATT LEVINE ...................................................................................................................... 303
MARK MCGRANAGHAN ...................................................................................................... 312
PATRICK MCKENZIE ........................................................................................................... 323
TRACY OSBORN ................................................................................................................... 343
DANIEL VASSALLO .............................................................................................................. 352
CASSIDY WILLIAMS ............................................................................................................. 362
APPENDIX B: THE 9 QUESTIONS WORKSHEET .........................................372
APPENDIX C: SOURCES .......................................................................................375
ACKNOWLEDGEMENTS ......................................................................................378
LEGAL ........................................................................................................................378

vi
Prologue: Why Write Technical Content
Whe e f ha a i l g e; ha c e,
In yours and my discharge.
The Tempest, William Shakespeare
Writing and publishing are incredibly rewarding, with tangible and
intangible benefits. I write to increase my skills, earn an audience,
teach what I know, and, yes, make money. Regardless of why you
write, this guide aims to provide you with the techniques you will
need to reach your goals.
I write about technical matters including front-end development,
Django, genetic algorithms, agile development, text-to-speech
systems, and localizing content, along with blog posts, email
newsletters, poetry, and personal essays. I never begin writing an
article as a complete expert on the subject in question. Combining
previous experience and research allows me to adapt my skills and
explore areas of programming that I would not otherwise
investigate. Cassidy Williams, one of the eleven experts I
interviewed for this book, shares her thoughts on teaching as
learning:
Learning by teaching is great because you have to put
yourself in the mind of a learner. A topic that you might
think that you know a lot about, you find out that you
d , he ac all a eachi g i a d a e i g
questions for people and trying to cover all of the
different use cases and misunderstandings that someone
might have. You start to learn a topic so much more
deeply than you would have if you were just learning it
on your own. I like teaching, not only to interact with the

1
 de c i ,b al j beca e i a g ea a
learn. Cassidy Williams
Writing is hard work, but reaching enthusiastic readers is a great
reward. Feedback, both positive and (constructively) negative,
keeps me motivated to improve my craft. Getting thousands of
views on an article is validating but requires that I make every effort
to ensure that my content is complete and accurate.
There is an incredible dearth of high-quality technical
content on the web. The flip side of this is that if you
write good content and present it in a compelling way,
you can get a lot of traffic. Mark McGranaghan
This does not mean that no great technical content is available on
the internet. Stack Overflow and other forums, magazines and
documentation, personal blogs and public repositories are all
fantastic sources of knowledge that have been invaluable in my
software development and writing projects. It is a great privilege to
contribute my own work to the ever-expanding community.
S e f he be c e ca ide, he he i
technical writing or advice or even inspirational stories,
should be content that empowers the people who read it
rather than merely answering a question, trying to
provide your own viewpoint on things, or other self-
focused content. Courtland Allen
If I have deceived you into thinking that I am writing out of selfless
virtue, just skip ahead to Chapter 11, which covers pricing. I began
writing as an additional source of income, and it is only because of
the relatively high demand and compensation for technical writing
(as opposed to fiction or general nonfiction of similar lengths) that I
am able to write as much as I do. Writing technical articles will not

2
make you rich, but per-article fees of several hundred dollars add
a b a ial le e a e b li e.
If you are writing for your own sites without direct monetization,
writing can still have a great effect on your career.
I have a relatively modest online presence. Right now I
have a few articles on my site, but I get all kinds of
interesting inbounds, people who write about stuff that
I e i e ab . Tha al e c d e i e if
you do it right. I wrote Go by Example six or eight years
ago, but that continues to generate and deliver value to
me over time. Mark McGranaghan
You have already bought this book, thank you. That means I do
not need to spend any more time selling you on the benefits of the
c af . Le ge igh i i.

3
Chapter 0: You and Your Guide
If you have read similar books on writing in other fields, for
example, a recent copy of W i e Ma ke , many of the ideas in
this book will seem surprising, or even wrong. This book is
designed to teach you how to write complete, accurate, and
compelling technical articles and tutorials, and how to sell your
work to clients. This market, thanks to its adjacency to software
engineering, is substantially different from markets for short fiction,
essays, recipes, journalism, or even informational articles on topics
like personal finance or marketing.
I wrote this book to address the gap in existing resources that I
discovered when starting out as a writer, and I am not alone in
seeking more and better information about writing for software
developers.
The e hi di c ec i he ld f ech ical i i g
between what we do a i , he e le h e
interviewing and technical writing as a field over the last
twe ea . The e hi diffe e ce be ee ii g
camera manuals and airplane-part manufacturing
manuals and writing API documentation and how-to
g ide a d ial f de el e . The e a h ge lack
of canonical literature in best practices, things people
should be doing, things people are doing. Angel
Guarisma
0.1 Intended Audience
While I am a software engineer, I imagine a broader readership for
this guide. I hope that every engineer, analyst, researcher, and
technician who comes across this work is able to apply it to their
writing and find success in their field. This book is primarily

4
focused on writing about software and related fields, because that is
where I have the experience to write confidently on the topic.
Examples, interviews, and anecdotes are from the software
engineering perspective.
Do not worry if you are coming to this book and do not identify as
a writer. Aspects of your personal, educational, professional, and
technical background will combine with practice to help you create
your unique voice and enhance your ability to put words on the
page.
I used to write a lot at Amazon i a e i i g-heavy
company. Pretty much all communication gets done in
writing; there are very few presentations and meetings,
and documents tend to be significantly preferred.
Nevertheless, I think probably what I took from Amazon
in terms of writing skills was a skill for concision. When I
entered Amazon, I used to spell out all of the details and
everything. I think I got a sense of better reducing and
eli i a i g de ail ha d eall a e ha dil e
he c e . I ld a I ha e a a ic la
background or skills in writing, from college or
elsewhere. Daniel Vassallo
Even if writing is not a strong skill of yours, you can create great
technical content.
My university professors would probably all say that I
a a a f l, a f l i e . I f ha I e i e a d
self-published three books so far.
Tech ical c e i f . I feel like i eall
writing sometimes. One of my conference talks was
talking about technical writing and trying to encourage

5
 people to write more in a down-to-earth, friendly
a e , like I e bee alki g hi h e call. Tha
h I a ha d ha e feel like ea ie
in order to get information across. One thing that really
helps me is to visualize sitting next to someone and
talking them through something, and then I write it that
way. Tracy Osborn

0.2 About This Handbook

This guide is composed of three acts. First, we will walk through
the entire process of writing an article, from pitch to content,
editing to publication. Next, we will explore the process in action
with three full sample articles. Finally, we will discuss the business
of writing and how to turn your newfound confidence in the article-
writing process into a profitable side gig or even full-time
employment. Along the way, we will hear from successful members
of the software/writing community about their best practices. These
excerpts are lightly edited for readability. Full transcripts of each
interview are available in Appendix A, and I encourage you to read
all eleven complete interviews as they are loaded with valuable
insights.
I am grateful to everyone who took the time to discuss their work
and insights with me for this book. Here is an alphabetical list of
the eleven people with whom I spoke and a few sentences about
why I am so excited to share their wisdom with you.
1. Courtland Allen is the founder of Indie Hackers, an online
community for people working on independent bootstrapped
businesses, of which I am proud to count myself as a member.
Indie Hackers, now owned by Stripe, has been a source of
knowledge and inspiration to me throughout the process of

6
 writing this book. Allen has interviewed over five hundred
founders for his site and podcast.
2. Jeff Atwood is the writer of Coding Horror (one of the
i e e l ge -running and most popular technical blogs),
co-founder of Stack Overflow and the Stack Exchange
network (one of the 100 highest-traffic sites in the United
States), and co-founder of Discourse (a provider of open-
source forum software aiming to improve the state of online
communication).
3. Chris on Code started scotch.io with his childhood friend
Nick Cerminara to publish articles and courses on front-end
development. Under his care, the site grew to four million
monthly page views and published over five hundred guest
authors before he sold Scotch to Digital Ocean in late 2019.
He joined the company as a web community manager.
4. Peter Cooper runs Cooper Press, a publisher of a dozen
email newsletters with a combined distribution of almost half
a million developers at the time of writing. He reads countless
technical articles in search of the best content to share with his
subscribers.
5. Angel Guarisma eats, sleeps, and breathes documentation. At
the time of our interview, he was the Director of Content at
Linode, a cloud computing company with a major presence in
the open source community. He now works as the Director of
Product Education at Humio. At Linode, Guarisma led an in-
house team of technical writers and editors and works with
numerous freelancers to publish wide-ranging and
comprehensive tutorials and documentation.
6. Matt Levine is a columnist at Bloomberg where he writes
Money Stuff, an incredibly popular weekday newsletter on
finance that is widely read in the tech sector. Previously, he
wrote at Dealbreaker, and he has written for The Wall Street

7
 Journal, CNN.com, and NPR. While his substantial
experience is entirely outside writing about software, his
techniques and insights are applicable to the work we do.
7. Mark McGranaghan created Go by Example, a website for
teaching the programming language Go. Go by Example drew
attention for its two-column design and quality example code.
Today, he works at Ink & Switch, a research lab that produces
reports and spin-off companies in consumer software.
8. Patrick McKenzie has been writing on his website,
kalzumeus.com, since 2006. He has written over five hundred
articles about lessons learned working on Bingo Card Creator,
Appointment Reminder, and Starfighter, consulting for
software companies on engineering and marketing, and most
recently working on Atlas for Stripe. He is also the third
highest-ranked user of all time by upvotes on Hacker News.
9. Tracy Osborn is a writer and conference speaker. She has
bli hed h ee b k de he Hell Web e ie : Hello
Web App, Hello Web App Intermediate Concepts, and
Hello Web Design. She is a frequent speaker at numerous
events, writes extensively on her personal website, and
currently works at TinySeed.
10. Daniel Vassallo worked at AWS for eight years. After quitting
to work for himself, one of the first things he created was the
self-published ebook The Good Parts of AWS, with Josh
P ch . Tha k i la ge a Va all a die ce
Twitter, which he earned by sharing detailed insights into his
work, the book sold thousands of copies in its first three
months on the market, generating over $50,000 in revenue.
11. Cassidy Williams has spent years working in developer
evangelism, speaking at dozens of conferences, and writing
technical content, including the Stack Overflow newsletter. At
the time of the interview, she taught with React Training. She

8
 now works at Netlify. She publishes a weekly newsletter,
rendezvous with cassidoo.
This book, like every book, does not contain everything there is to
know about its subject. It does not contain any legal advice and is
no substitute for legal guidance on working as a freelancer. I
encourage you to read the full text of each interview for wisdom
that I could not squeeze into the main text and to visit sources from
Appendix C that pique your interest. On the topics that I do cover,
I have endeavored to be complete in my treatment, and have noted
inadequacies in a few discussions where appropriate.
I be e ha e half f a b k ha a half-baked book
if you k ha I ea ; i be e c e half he
topics but be well-written and well rounded rather than
mention things but not elaborate on them enough.
Daniel Vassallo
I prefer to think of this book as three books in one rather than half
of a book. I hope it both satisfies your immediate interest and
needs and sends you down a path of building your own writing
practice. Thank you for reading Writing for Software Developers.

9
Act 1: The Craft
O, i ee
When in one line two crafts directly meet.
Hamlet, William Shakespeare
Every part of your writing process can become reliable and
repeatable, if not replicable. Discovering which strategies are
consistently effective in your own work unlocks progressions in the
quantity and quality of your writing. Some processes are
transferable; I can tell you exactly what works for me and you can
expect success with the same tactics. For the others, I will guide you
through my thought process, giving you a scaffold to use in
constructing your own practices.
Tech ical i i g i e ha j a ial; i
connecting you with teaching somebody across the table
f a d ha ha I l e ab i . Chris on
Code
This act begins with a replicable idea-generating process designed
to turn your collected experience into dozens of compelling article
ideas. The second chapter presents a step-by-step guide to finding
publishers who can give your work polish and reach. Pitching your
ideas to your publisher is not just about getting someone to
purchase your article, it is about forming a partnership to support
you throughout the writing process. In Chapter 3 we turn to
research, where you learn to leverage your debugging experience to
quickly find and analyze relevant sources. Chapter 4 discusses
outlining your article and producing sample code in preparation
for writing. Chapter 5, which covers writing, explores my process to
assist you in constructing your own. Chapter 6 considers what to do
after an article is written, explaining steps you can take to improve

10
your own work and the assistance you should expect from your
editors. The seventh and final chapter in this act discusses the last
e f hi i g k, i h i f ai b h bli he
practices and publishing platforms.
This entire act approaches writing with the goal of developing
technical tutorials of approximately two thousand words for an
audience of software developers and selling that work to publishers.
I focus on this for three reasons:
1. Writing a 2,000-word tutorial is an achievable goal for your
first piece of technical content.
2. Well-crafted technical tutorials have high demand from both
publishers and readers.
3. Most of my experience is in crafting these kinds of articles.
However, the strategies developed in this act are more broadly
applicable. If you are writing anything from documentation for a
project to a book on a technical topic to material for a class or a
video, I think you will find this information immediately actionable.
To get us started, I would like to share a story from Jeff Atwood
about why he admires the book Code Complete by Steve
McConnell.
The main thing that was really illuminating about the
b k i ha i i e i hi eall h a e. I
ab M b ai i bigge ha . I e about
the process: how do we manage this process to minimize
the human element of error? How can you manage the
h a ele e fe a d i ake ha g i g be i
every project, and how can you understand the
eak e e ha e a a h a ? B I mean
everyone. We all have these personal failings. We all

11
have pride attached to our work that may be misplaced.
We all want to think of ourselves as perfect people. But
i eali , e e . I a e i e e i g ha he b k
attacked the human side of the problem rather than
elli g h i e e fec c de. I did a , J
f ll he e c di g g ideli e a d ll i e e fec
c de. The a ach a e ab h a age
your own psyche how to manage your own emotion
ch ha e capable of producing your best work. I
thought that was a very deep, deep message, deeper than
programming. Also very, very true: programming is
people.
If you have a team that is all pissed off and hates each
he , he e g i g i e e ible c de. I d ca e
h ale ed he a e, if he e ad a each he ,
i ed ff, ha , i j g i g be bad. Tha a
the key insight of Code Complete for me: programming
is the art of dealing with people. You think of
programming as the art of dealing with the computer, but
the computer is pretty much this dumb, dumb machine.
I ea deal i h he c e . F he a ,
ha diffic l i deali g i h he e le, ea ,
your manager, your project, and the people who pay you
money for he jec . Tha he eall diffic l a a d
ha he a ha he b k eall del e i . I d e
talk about code, but it spends a lot of time talking about
personal character and the emotions of the people on
your team and how to have a sustainable jec ha
not breaking the people working on it. I still love those
ic . Th e a e i ele ic , a d ha h i ch
a g ea b k. Tha h i d e e e eall ge f
da e, beca e e le a e g i g cha ge f he e

12
ten thousand years, not in that way. In a hundred years
e ll be i g adicall diffe e li g, b e le ill
ill be i ed ff a each he . I ll ell ha i h e-
hundred percent certainty. Jeff Atwood

13
Chapter 1: Finding and Validating Ideas
The first step is knowing what you want to write about. If you
picked up this book with a burning idea in mind, that is great.
Write it down with as much detail as you can, and then follow the
steps in this chapter to come up with ideas two through twenty. If
you are starting from scratch, do not worry. Coming up with
validated, well-scoped article ideas is not a daunting task when
approached methodically. This chapter describes the exact process
I have formulated through trial and error and repeated experience
to generate well-scoped articles with market demand. My ideas rely
on my existing skills and often prompt me to explore concepts that
further my own learning.
Every engineer has at least one good guide in them.
Angel Guarisma
I used to struggle to generate article ideas. I also used to rely solely
on moments of inspiration to keep my content pipeline full. When
I would pitch editors, it would take half an hour to write the email
because I would have to scramble to find a decent topic and
f la e a ea able i ch. I ed d ead he h a e e d e
ac le f idea . F he fi e a icle ha I e, e e
well-scoped topic with an outline that I actually stuck to was a
miracle. More than once I had to cover my mistakes with an
a l ge ic d ad e ii f ei he he a icle c e i
delivery date.
This was a bad system and led to me working through some
needlessly difficult rewriting to try to recover from insufficiently
thought-out pitches. To fix this issue, I created a more rigorous
system of idea generation and evaluation. Now, I maintain a list of
dozens of un-pitched article ideas waiting to take spots in my

14
publication schedule as repeat clients ask for new work and I find
new publications to pitch to.
There are several angles to consider when determining what to
write about. Your existing skills, experience, and interests; your
ec i e clie eed a d a ; a d ential
eade hi k ledge, d ai , a d a e i a all alig
to create a great outcome for all parties. While prudent writers do
consider their audience, both the publisher and the reader, in the
planning process, you should start with yourself. If you are not
writing about topics that you find intrinsically interesting and that
are within your skillset (or ability to learn), it will not matter what
the other parties think because there will never be a finished article
for them to read.
For the rest of this chapter, we will mostly assume that there exist
publishers and readers with your same interests. While we will
c ide e i i g clie i e e a d he e ial eade hi ,
future chapters will explore these constituencies in greater depth.

1.1 The 9 Questions Process

Set aside fifteen minutes with your favorite thinking tool (pen and
paper, notes app, sidewalk chalk) to generate answers to these nine
questions. Each question is designed to expand the list of potential
topics, not constrain it. Write down everything you can possibly
think of for each question, even if it does not feel possible right
away. The next step will narrow your focus.
Run this exercise before you start writing or pitching clients and
run it again if your backlog of ideas ever gets uncomfortably low.
Ideally, after working through this process a few times, the
questions will become second nature to the point that fully formed
ideas are occurring to you just as often as you can execute them.

15
1.1.1 Questions
The questions are broken into groups of three by category. As an
example, I completed the exercise myself; my answers are included
at the end of this chapter. You may wish to use the worksheet
included in Appendix B to complete the exercise.
Language Questions:
1. What programming languages do you know well enough to
write about?
2. What frameworks and libraries within those languages do you
enjoy using?
3. What company-specific technologies do you know well?
These three questions are very straightforward. Remember that you
do not need to be an expert on a topic to teach it. If you have
substantial experience, that is great, but as an intermediate
practitioner of a language or framework, you remember what you
struggled with as a beginner and can help others reach your level.
We often overestimate the expertise or the knowledge of
he ge e al blic i e f e hi g ha e e
ki g . Ma be e bee ki g OA h
authentication in Rails for the last three weeks. Well, you
are now at the top 0.01 percent of programmers around
the world at OAuth authentication with Rails. It might
feel obvious now because you spent three weeks working
on it, but approximately everyone else has no idea how it
k .Y igh be lea a l i ed if ie
something that seems obvious to you. You might get a lot
f e le h a , W I did k h ha
ked a d ha i e hel f l. D be di c aged

16
 from writing about topics that seem obvious. Mark
McGranaghan
As a writer, you are introducing your readers to more than just
technologies; you are introducing them to new ways of thinking and
solving problems. Consider how technologies you know fit together
and think about meta aspects like their community, support, and
popularity.
Whe e lea i g eb a de el ent with
P h , i eall ef l a i h Dja g . I l e he
Django community. I think that out of all of the
programming communities, it is the most friendly to
beginners. There are lots of beginner events including
Django Girls running workshops all over the US and
Europe. The Django conferences are beginner-friendly
and encourage beginners. I like Django not only for the
fact that it has all of the bits included, but also because I
k ha if I g i g b i g a e ga e i a
community, this community is going to support them.
Tracy Osborn
Topic Questions:
4. Which topic domains are you interested in?
5. Who are your clients and what topic domains are they
interested in? (It is okay to skip this question until you have
read Chapter 2.)
6. Who would you like to land as clients and what topic domains
are they interested in? (More about this in Chapter 2.)
Now that you have figured out what you can do, it is time for the
fun part: figuring out what you want to do. Think of topic domains
by developer-centered divisions, like data science and front-end

17
development, but also by real-world application, like finance or
medicine. If you do not have clients yet, skip number five, and if
you are not looking for new clients, skip number six. However,
never le e ce i f clie i e e c i ce
skip number four. I have written about web scraping for an AI blog
and AWS for a front-end magazine; editors tend to respond well to
enthusiastic pitches, even for topics where the connection is
tangential.
For question four, do not forget to list domains outside of
programming that you are familiar with.
Domain-specific knowledge is very, very useful in writing.
A e ca g a d lea a ech l g a d a , Al igh ,
he e h ie fi ga i P h , b
have no real background in it. However, if someone is an
astrophysicist or a biochemist or a marketing growth
expert and they learn how to use Python, it becomes,
H ie hi g i P h ha i ele a
to being a a h ici . Tha ag ifie he i i g
value by a hundred-fold, not merely by being more
specific in the topic but also being specific in the
problem space. There is domain-specific knowledge that
you know is going to go into an article like that. The
writer is going to write from the perspective of, say, a
bi che i a d he e e e fe e le d i g ha , i
adds a ton of value straight away. Peter Cooper
Experience Questions:
7. What relevant prior projects have you done?
8. What real-world systems have you studied and could reverse
engineer?
9. What environments have you programmed in?

18
Question seven is of vital importance. Having a prior project, even
if it is not in great shape, that you can reuse all or part of as the
foundation of an article makes the pitching, researching, outlining,
and writing processes all substantially easier. Most of the first
articles I wrote were based on personal or school projects that I
had completed and could adapt to teach a concept. For example,
the first article I wrote for FloydHub was about genetic algorithms.
Though the final product was a series of examples of basic genetic
algorithms in Python, the inspiration was a school project from
over a year prior intended to teach object-oriented programming in
Java.
Al f [ ha I i e] i i fl e ced b ha I d i g i
my personal projects, and a lot of it is influenced by a
certain timeliness to articles that help them gain traffic. If
Svelte has just come out then you write about Svelte for a
little bit. I think that what a lot of people do is start by
trying to figure out what projects would make a good
article topic, but I try to break it down a little further than
ha . A k, Wha i a g d jec ? a d he , Wha
are the components ha ake ha g d jec ?
Then, I try to break down every component into its own
article so that people can try to piece together one, two,
or even three articles. Chris on Code
Good answers to question eight make great articles. The logic of
modeling or reverse engineering a real-world system is easy for
your readers to follow and thus provides a good structure to the
article. You can add and remove details where appropriate to bring
the article to the desired length and knowledge level.
Question nine is independent of the previous two. By
environment, I do not mean IDEs or frameworks, but real-world

19
situations in which you have written code. Academic backgrounds
outside of computer science, the industry you work in and its
domain-specific problems, or targeting a particular group of users
are all interesting filters. Adding any one of those perspectives to an
article can make the content uniquely engaging to a narrower
market, which, unless taken to the extreme, is a good thing. Think
about problems that you faced working in those environments. Do
other people struggle with the same issues? If they do, solving a
problem from your chosen environment is a great basis for an
article.
You have to be thinking not selfishly but selflessly;
explain this problem and that helps not just me but
everyone else that has this problem. Now to be fair, there
could be some super narrow problem that only one
person will ever have, but in reality most problems
e le i a fai be f i e , a d i be
ca ha c ce a di i da e
starting. Jeff Atwood
1.1.2 Merging Answers
Reading over your answers will help article ideas form in your
head. Write them down. A complete map would combine each
answer to each question with every combination of every answer
from every other question. Fortunately, we do not need to run that
O(N^9) algorithm to find compelling article ideas. Instead, focus
on taking one element from each category and seeing how they
work together. Start by performing the obvious combinations, but
do not neglect the surprising ones. What would it mean to write
about using R to explore front-end development for startups
looking to build chat apps? At first, it seems like these topics have
little to do with each other, but a bit of creative brainstorming could

20
lead to an article on building a web dashboard for analytics on real-
time data.
For each combination that makes any amount of sense, write a
couple of sentences describing the contents of the article. This is
not a formal outline, just a brief description of the idea, enough so
that you will be able to come back later and pick up on your
thought process.
Also, write titles. Titles are a great way of narrowing down your
audience. These are working titles; they do not have to make it to
blica i . The f la T ic i La g age f
E i e C ea i g S e i g F a e k( )
should get the job done in most cases. Keep your titles precise and
relevant; eschew clickbait.
A perennial issue is focusing on titles. We did see a
trend three to four years ago back where people were
trying to be very clickbaity with titles. There were all
kinds of publishing companies and sites that would take
feel-good stories from the media and write these really
long titles for he ih a d belie e ha
ha e ed e ! F e a le, S e e f d e c e
ki e i a bag a d belie e ha ha e ed
e . The ld ha ,b i ld j be a
video like a YouTube embed or something and all they
were doing was siphoning all of the traffic with these
clickbai headli e f hi g . Pe le a e bec i g
i e i , a d he e bec i g fa ig ed, i he a e a
they became fatigued by banner ads and things like that.
Peter Cooper
Throw away any article ideas that do not appeal to you or seem
blatantly impossible, but try to keep an open mind about what you

21
want to write throughout this nine questions process. Once you
have fully concluded your brainstorming, you can move on to
winnowing the list down to sure winners.

1.2 Idea Validation

At this point, you want to get a rough sense of the scope of and
market for each idea before committing to pitching or writing any
one of them. If you have ever performed market research for a
product idea, it is a similar process, but it is also much easier and
scaled-down. You do not have to perform nearly as thorough a
validation for three reasons:
1. Articles have a low opportunity cost to create.
2. Articles are very flexible in scope.
3. Articles can coexist with very similar work while still providing
value.
The opportunity cost of unsellable articles is fairly low as they only
take a few hours to write and can often be repurposed or published
on your personal site. Thus, you do not need to do as much
market validation for an article as you would for a minimum viable
product, which might take a hundred hours or more to develop.
However, it is still important to perform these validation steps; it is
better to sink five minutes into thinking up an idea that you cannot
execute than five hours writing an article that you cannot publish.
For a book or larger work, winnowing down ideas is a much more
intensive process.
The main filter that I wanted to apply was that I only
wanted to write about things that I was very intimately
familiar with. AWS is a vast topic meaning there are
h d ed f e ice i cl di g l f hi g I e e e
ed elf. Ba icall , I did a d a e ea ch

22
 or experimentation. I wanted something that could pretty
much write itself, something that was basically a brain
dump of things that I knew intimately, where I knew
what I wanted to say. In the introduction we mentioned
that we only talk about things that we have significant
first-hand experience with. That was the first cut.
Then there were a few he hi g ha did ake i .
Ironically one of the products that my co-author and I
ked el e he a AWS, e did i cl de i
the book. It was part of the time-boxing process. We
tried to group things that were related. The second thing
i ha e lef hi g ha did ela e ge he . The
theme was infrastructure-related topics; there were other
things like application monitoring and things like that
which we could have included we have first-hand
experience with these things but they would have made
the book significantly bigger and would have taken longer
to do. To be honest, we thought that it might be a good
candidate for a sequel, a part two on a different topic set.
Daniel Vassallo
You can get a lot done in two thousand words, a hundred lines of
code, and maybe a chart or two. The key issue, which we will
explore in Section 4.1, is appropriately scoping your sample
application or topic outline to include only relevant information
and assume the right level of background knowledge. Right now,
you mostly want to make sure that you are within the right order of
magnitude. Some publications offer quick tips, writing about the
semantics of a single line of code or short snippet might need
expanding. On the opposite end of the spectrum, a topic like
Maki g a Web i e i Dja g ld eed be b ke d
substantially to extract achievable topics for single articles.

23
 We started Scotch with a lot of these simpler articles:
how to do form validation in Angular, how to do it in
React, how to handle event inputs in Vue. Then, we got
a i he e e aid, Ok, le d he e eall c l
long-f a icle , he e e ld d , H B ild
XYZ i h Tech l g 1, Tech l g 2, 3, a d 4.
What we found was that a few people read and followed
through on those articles, but far fewer than the broader-
term articles. Chris on Code
When you have an idea, make sure there is a demand for it.
Search for key terms for your title as if you were a reader trying to
find your article. Skim the top few hits. If your idea turns out to be
wholly original, then that is great, but you will need to do extra
research to make sure there is an interested readership for it.
Finding other articles on your topic is not a bad thing; on the
contrary, it means that you have identified something interesting
enough for other people to write about. However, if there are
hundreds of articles, books, videos, and other resources on the
topic (for example, say you want to write a general introduction to
programming in Python), you will have to carefully consider your
angle to stand out from the crowd. This angle could come from an
answer to question four or question nine. Also, check the dates on
the articles you find. If you are writing about a specific
implementation and the best competing article is, say, five years
old, for many topics that means your fresh take might be
marketable. After this validation step, note any similar articles you
find, as they will make good sources in the research phase.
Now is also a great time to audit the previous projects that you are
using for inspiration. Make sure that you have the appropriate
rights to repurpose the code and are not bound by any
employment restrictions or other contractual obligations not to

24
write about a given subject. For showstoppers like that, it is best to
get ahead of the issue early.

1.3 Article Lifespan

In the validation phase, we considered how competing articles have
aged to see if there was a market need for your idea. Now, we will
think about what will happen to what you write over time.
I i g i e ab hi g ha a e , He e
ech l g f hi a ic la ea . Y e i g elf
too much to very specific bits of technology and specific
bi f i e. Y e l ki g a he e imeless
aspects of the underlying principles, the underlying
human factors. If you look at my early blog, I did write
about some very technical stuff that now seems
completely pointless. It might have mattered for like a
ea , b b d g i g ca e about that post
a e. Tha fi e. If l k a he e ha eall
a e , i ab he dee e h a i e f h e ge
better at doing this as people. How do we become better
e i f el e ? If a i e ff ha
going to last, ha g i g ha e a l g helf life,
want to avoid really meticulous, detailed, in-depth
technical stuff because it has such a short shelf life in the
big picture of things. Jeff Atwood
While it can be valuable to focus on long-term trends and
evergreen ideas, there is also a lot of value in up-to-date technical
content. Publishers prove this value with their demand for
technical tutorials.
If i hel f l a d eache a ble e le a e ha i g
i h c e ech l g , i g i e hat. You

25
 have to mix it up, though. You have to write a variety of
content. Some percent of your content can be current
technology and another percent should be relatively
more timeless things about how to run projects, how to
deal with people, how to deal with emotions things that
are more about sustainability in your career. For every
i e ab ff ha ha e i g hi ea , i e
a ha g i g be ele a e ea f .T
i i , a d kee a g d bala ce g i g. I
sa i g d i e ab c e ech l g I ba icall
he h b h gi l. Wh b h? Jeff Atwood
Taking this idea a step further, you should write one-year articles
for your clients and publish ten-year articles for yourself. This way,
you get immediate payment for the shorter-lived work while the
client bears the depreciation, and you accumulate the long-term
benefits of having published a sustained resource. Publishing
articles with a longer shelf life for yourself will help you build a
strong presence with fewer pieces than if your writing goes out of
date every year.
I e bee ii g fe i all i ce a lea 2006. I
spent a lot of cycles early in my writing career writing
things that depreciated quickly, in the economic sense.
For example, writing about the current best practice on
Rails, especially back when Rails was moving at rapid
speed, did not set me up for long-term professional
success. I would probably not write on that topic today,
particularly not if I was writing in a concerted fashion.
The reason for that is that, as you mentioned, there are
some posts that maintain their value after ten years and
then there are some posts that are, like the Rails article,
probably good for about eighteen months. Eighteen

26
months might sound like a long time. There are many
written artifacts that lose more than ninety percent of
their value within twenty-four hours. I like to say that
The New York Times throws out more excellent writing
than you will produce in your entire career every day
because the value of the ninety-fifth percentile New York
Times piece after forty-eight hours approaches zero.
Given that you are vastly less resourced than The New
York Times and you probably have a longer scale with
regards to your decision-making horizon, you should
intentionally try to get more of your pieces into the
bucket where they will continue to be valuable for years
ahead.
In 2012 I wrote a piece on salary negotiation advice for
engineers, and because I was writing on blog software
and blog software generally includes the date
prominently all over the piece, I routinely get questions
ab ha iece a ki g I hi ad ice ill g d? Tha
a frustrating question for me to be asked: of course the
world has not advanced so much between 2012 and
2020 such that not negotiating your salary is suddenly a
good idea. The thesis of that piece is that you should
always negotiate your salary. Just the fact that I made the
date so prominent in the piece caused people to believe
that as soon as the date changed, which happens literally
every day, then the piece starts losing value. I am more
intentional now in writing to position my pieces as essays
rather than blog posts, because essays have an anchor
around timelessness and blog posts have an anchor
around being up-to-the- e . I i e i all ii g
most of my essays on subjects that will continue to be
relevant to my readers in ten years. Patrick McKenzie

27
This is also a good deal for your client. Their economics are
substantially different from yours such that they can create a viable
business model on content with a primary relevance that lasts for a
few years at best.
There exist publishers of technical content that either
have much better monetization options with respect to
one reader than an independent writer of technical
content would, or they are selling something that is not
itself content and so their investment in content is
essentially a marketing expense for the core thing. For
example, I work at a large software company. The core
economics of large software companies are extremely
healthy. The market characteristics of my employer are a
bit different than the typical enterprise software
company, but the typical enterprise software company
might have margins approaching one hundred percent
with deal sizes in the five or six figures. They can justify
an awful lot of spending on a daily basis to produce
content if it successfully gets decision makers for their
i d ge i ch i h he ale e . Tha d e
work out quite so well if y e a i di id al e gi ee
yourself and you have some allocation to make of doing
core billable work versus investing in your own
marketing; you would generally want to write artifacts that
would continue having value even in weeks or quarters
where you were primarily doing billable work. Patrick
McKenzie
Not only are many publishers able to better monetize depreciating
work, but some extract long-term value from it. If a publisher
invests in keeping their old tutorials up to date, they can get fresh

28
technical content for a smaller investment than commissioning
original work.
Wi h a lib a a la ge a he e ha e ha e e el
on our open-source community to flag things that need
to be updated for us. Or, because our library is open-
source, community members might just make the update
he el e a d e ll e ie i . We al ha e eb d
on staff who is dedicated to updating things one person
on the team who basically takes feedback from the
community in the form of comments, GitHub issues,
etc., and updates documentation accordingly. When a
e e i c e f e hi g, e e able ge
it as fast as possible.
Whe e e a i e a a iece f d c e a i , i
i a ha e ac all e di g he ff
the wrong track. Even if you write it really well, people
still just skim down to the thing that they need, so they
c ld i ha ha he e l ki g a i ab he
right version or something. We put deprecated
notifications on guides, and we do this very purposefully
because sometimes people use legacy systems and they
need a Debian 5 version of a piece of documentation
beca e ha ha he e i g. B , eb d ill
a i e he e a d i he gia ba e ha ead , D
l k a hi g ide if e i g Debia 5.
The reason that we write documentation here at Linode
is to be genuinely helpful and to inspire confidence in
people. We have to make that investment to hit both of
those things ca be ge i el hel f l if e
updating your documentati a d ca i i e

29
 confidence if somebody breaks their system after
following your advice. Angel Guarisma
Tech moves fast, but many people still work with legacy systems
every day and need high quality resources to help them solve their
problems.
We rarely delete versions because of the edge case
where people use legacy systems and come to those old
versions directly. Angel Guarisma
The good news is that even if there is a competing technical tutorial
of high quality, it might be old enough that your fresher take on the
topic is still needed. The bad news is that it is really hard to write
evergreen technical content beyond basic introductions because
systems change so quickly. It is up to publishers to worry about
keeping their content up to date. As a writer, I focus on creating my
best work in the moment while making an educated guess
ega di g k l ge i .

//TODO
1. Complete the 9 Questions Process Worksheet from
Appendix B.
2. Combine your answers in as many ways as you can think of to
generate article ideas. Try to come up with at least ten titles.
3. Pick the three titles that you are the most interested in writing.
For each title, search keywords related to the topic to see if
there is room on the market for your article.
Here are my answers to the worksheet. (In between answering
these questions and publishing this book, I actually wrote and
published an article with CSS Tricks based on my answers to this
exercise, which I had not planned to do.)

30
Some answers from the worksheet are circled. These answers
inform three titles we will be considering throughout this book.
The tutorials Scraping Shakespearean Sonnets and Shakespeare-
Style Sonnet Generator along with the technical article
Computational Poetry are based on the circled ideas. These
articles are presented and discussed in full in Act 2.

31
The 9 Questions Process Example

32
33
34
Chapter 2: Publishers
Imagine a college student deciding that, for their first foray into
journalism, they would write a headline story for The New York
Times. That is a fairly close metaphor for my leap into technical
publishing. After only a handful of previous publications, I
successfully pitched a two-article series to Smashing Magazine from
the dark pre-dawn swelter of my summer sublet in Somerville, MA.
Unlike writers who contribute to prestigious mainstream media,
you do not need impressive degrees or a packed résumé to write
for top technical publishers. If you can deliver quality work that
their audience wants to read, they will purchase and publish it.
Finding a publisher is an important early step in the writing
process. While a fiction author might only begin querying after
crafting a fully polished piece, technical content publishers ask for
pitches, not finished work and, once they have signed on to a
project, they are involved at every stage in the writing process. I am
i g he e bli he l el i hi b k. While there are
online and even print magazines in a variety of software and
software-adjacent topics, from both independent and legacy
publishers, there is a lot of demand from company blogs,
documentation projects, and corporate users. For the purposes of
this book, any opportunity that will accord your writing the editorial
attention, publicity, and compensation that it deserves is a
publisher.
No matter how you slice it, the general market for written words is
ab e a ke . I hi f -cited book On Writing, Stephen King
describes how he received dozens of rejections from publications
before his first works were published, and even after his first
success it took years before he got his writing regularly accepted. In
my first year of publishing, I had a per-pitch success rate of about

35
fifty percent for first-time clients, much higher for repeat clients. I
am not nearly as accomplished as Stephen King. I am not as skilled
as Stephen King was when he was twenty, either. The difference is,
the market for technical content is a fairly unique niche for a writer;
the supply is much lower and the demand much higher than
almost any other genre. The right mindset for approaching
technical content pitching is one of a freelance software engineer,
not a creative writer.
Why is it to your advantage to work with a publisher? After all, if
there is such demand for good technical content, you could publish
on your own website and retain all of the benefits for yourself. I
certainly encourage you to self-publish when so inclined, but there
are several benefits that good publishers provide. Payment and
publicity are great benefits, but the most important to your progress
is editorial feedback. Editors first validate your ideas by acting as a
gatekeeper and staking a small piece of their own reputation on the
legitimacy of your work. After a pitch is accepted, your editor will
help you develop a sense of what components are needed in an
article, what order it makes sense to present information, which
sections are needless digressions, and what other ways you can
improve your craft. This feedback cycle begins at the idea stage and
continues until the article is published.
The e a l f f c ea i g he be a icle i he
planning process. Chris on Code
This is the sort of feedback that you might need to hire a tutor or
coach to give you in other fields, but for technical writing the editor
will help you get better and pay for your work in the same
transaction. (A caveat: the piece you submit must be plausibly
publishable for it to be worth their time to edit.) A publication will
also promote your work once it is released, helping you find a

36
larger audience. Finally, when you are starting out, it can be hard to
assess the value of your own work. Getting paid for your writing
validates that your efforts are worthwhile.

2.1 Finding Publishers

I maintain whopaystechnicalwriters.com, a crowdsourced list of
publications looking for technical content. I would love to use that
data to provide you with a list of active publishers. Unfortunately,
any static list that I could compile would be both woefully
incomplete and immediately out of date. While I encourage you to
take a look at the site, at some point you will likely want to find
clients on your own. Here are a few key strategies that have helped
me find clients.
Begin your search for publishers at the sites that you enjoy reading.
Any subfield of software development has a few bigger publications
directed toward it, and if you are active in your field there should
be a few names you would recognize. Start your list of potential
clients with the names of your favorite publications to read.
Similarly, if you use a developer-focused product or service, you
should check if ha c a bl g bli he c e f
freelance writers. Once you have exhausted these options, it is time
to strike out into the wilds of the internet.
As a programmer, when I get an error, my first response is to do a
general Google search for the answer. Unfortunately, while this
approach is great for errors, it is not very productive for queries
like Tech ical i i g i ie a d i i g li e f
f a e de el e , hich e d ield l -quality listicles or
blog posts telling you why, but not where, you should write. Sorting
through the content farms and dead links listed on pages with titles
like 100+ lace i e li e ha a el f d e ef l lead .

37
M la ge bli he ha e W i e f U age he fficial
prog a f b a di g i e . Sea chi g W i e f U i
Google brings up useful results for me, although my extensive
search history around technical content may be boosting those
results. Regardless, if you have a history of searching for error
messages or technical documentation, going through the first ten or
age f e l f he e W i e f U ( i i h a d
without quotation marks) should yield a dozen or more leads. If it
d e , add ke d ela ed ic f i e e like CSS or
f a e. Al , he e a e he age ha h ld be l ki g f
on sites that you read to get guidance on how to pitch to them. A
query email should include only the specific information that the
W ief U age a k f .
Even if a site does no ha e a W i e f U age, if i ha a
content team or publication, they may be interested in hiring
freelancers. Cold email inquiries have been a very effective strategy
for me; I have a pretty high response rate on specifically targeted
queries to vet ed i e . Whe I a ecificall a ge ed, I ea I
write my queries carefully to avoid sounding like a template. Done
right, getting in somewhere that is not advertising for content can
lead to a reliable repeat client who appreciates your perspective
and work.
Getting other perspectives and fresh faces to be involved
i hi g i be eficial. Y ca d e e hi g elf.
Peter Cooper
Take your search to forums like Hacker News and Reddit. On
forums, users submit content, and that content has to come from
somewhere. Hacker News in particular has been a great source of
clients for me, both from pitching publications whose articles find
hei a he i e a d e di g i he c i

38
monthly freelance job thread. Even though these are great sources,
I have listed them last because it can be a lot of effort to sift
through a large quantity of forum posts or job listings to find the
right fit.

2.2 Pitching
The first time you write for any given publication, the pitching
process is fairly formal, and you probably need a complete outline.
As your relationship with a publisher and editor grows, your
pitches may become less fully formed but still be careful to
rigorously validate your idea to avoid having to kill an article in
development. This section will focus on first-time pitches, as the
process is significantly easier after you have proven to a given editor
that you are capable of producing work that they want to publish.
Generally, a pitch should spend just a few sentences establishing
yourself and your credibility. Prior writing experience (with links) is
nice, especially if it is for a comparable or recognizable publication,
but it is not necessary. Be creative in what you include as a sample;
if you do not have any articles published, a technical post on your
personal blog or even something like a thorough answer to a Stack
Overflow question can prove your technical writing ability.
Alternatively, if you have a lot of technical or industry experience,
publishers will be willing to work with you to develop your writing
chops. Chris on Code publishes a wide range of freelancers:
I like he e, The e a e i e e age , l
i e e e ge [Jadah Sell e ]. F a a h
personality to shine through is a big benefit. Get to know
he a h , fig e ha he e i e e ed i , a d ha
he e ki g . F he e i ba icall g e : ic
elec i a d li e c ea i , a d he e ll g back
and forth on the outline, and after that, they get to the

39
 rough draft, a d he i he e all edi i g ce a d
publication. Chris on Code
The bulk of the pitch will be your article ideas. You will usually
want to pitch two or three ideas at once, which is why it is so
important to develop a long list as you learned in Chapter 1.
Depending on the publication, they may want short pitches or full
outlines. Make sure your article ideas address the topics and
audience that the publication serves.
I al a l ki g f he ge e ic hi g ab
how to solve a proble ; I l ki g f h l ea
more specific problem for a more specific group of
e le. I d al like f a e be able ead i a d
gain some insight into the general problem. Peter
Cooper
2.2.1 Finding and Pitching Your Second Publisher
Once you have been published once, the few barriers that existed
in technical publishing will fall away. Most editors will be happy to
entertain your ideas if you can point them to published proof of
your ability to create great technical content. Do not rush to send a
pitch to every name on your list. Add clients slowly to ensure you
can meet the obligations you set for yourself.
In traditional short-form publishing, there is the practice of
i la e b i i he e a a h i e a i gle iece
and sends it to multiple publications at the same time. Because you
are pitching ideas, and these ideas should be targeted closely to
ec i e clie i e e , i i be e i ch each idea
one prospective client at a time. If the idea gets turned down, do
not lose hope, just bring it to another publisher.

40
It can work to pitch different ideas to different publishers at the
same time, but you will want to make sure you are not
overwhelmed if they all say yes. Editors get a lot of email. You
might not hear back about your pitch right away, but you should
within two weeks. At that time, send one follow-up pitch (unless
hei ief age e lici l a , hich e d ). I
can be helpful to send it from a different email address or from a
different medium (like LinkedIn) in case the original was blocked
by a spam filter. If they do not reply, move on. There are plenty of
publishers out there.
Once you have been published in a few different places, other
publishers may come to you for their content needs. Some of these
queries are spam, but some are legitimate and can arrive
surprisingly early in your writing journey. I have worked with two
clients who cold-contacted me after reading my work. When you
are accepting cold outreach, rather than pitching yourself, you have
more leverage to use to negotiate favorable pay, terms, or
deadlines. Negotiating in good faith can result in solid recurring
work and a strong relationship with the publisher.
You do need to be somewhat careful when finding sites to write
for. Generally, publishers should be explicit about providing
compensation, their editorial process, and other aspects of writing
with them. If you are not already familiar with the company, take a
look at other articles that they have published recently, as well as
their overall site design, to make sure it is the sort of place that you
think would reflect well on you and your work. Also, if you have
been in the industry for a while, you will start to recognize other
authors and note which sites they have worked for. This attests to
h e blica i c edibili , e eciall if he a h ha ked
there multiple times.

41
2.3 Working for an Agency
If the process of finding clients seems daunting and the other
aspects of building a business around your writing seem exhausting,
you might want to consider working for an agency. Technical
content agencies work with clients to develop content strategies and
hire writers and editors to create that content. The main advantage
of working for an agency is that all you have to do is produce great
work. You are handed a title and prompt, write an article, and send
i he age c edi ial aff. The age c b i g a ch
work as you want, without you having to chase down clients.
There are a number of downsides to working with an agency. First
off, you will get paid less than you would working directly with
clients, and you frequently will not get bylines or attribution like
you would if you worked with the publisher directly. Many of the
most prominent sites outside of corporate blogs do not work with
agencies, only individual authors. You have less creative freedom in
the work you create and you will write about what the agency and
client decide on.
I encourage you to at least try working directly with a couple of
clients before considering working with an agency, and for most
authors I would recommend exclusively working with publishers
directly. If you do decide to work for an agency, make sure it is
reputable. Ask to see recent publications, read their style guide,
and talk to an editor and a writer about their process. A good
agency will be proud of the work they create. Check their pricing
and make sure its consistent with their rates. Read your contract
with them carefully.

42
//TODO
1. Create a list of ten publishers you would like to write for. Visit
whopaystechnicalwriters.com, but see what you can find on
your own using the strategies in Section 2.1. While making
this list, assume you are the best writer to ever live and these
publications would be happy to accept anything you pitch
them (See step 3).
2. Review your three validated ideas from Chapter 1 and try to
match them to your list of publishers. If none of them seem to
fit, reach for other ideas from your list.
3. Write three pitches, one for each idea, and send them to the
a ia e bli he . Re e e e a i f
writing prowess; write the pitches with restrained, professional
confidence.

43
Chapter 3: Research
After generating an exciting topic and finding the right publisher,
my last step before writing is research. It is important to understand
prior work on your topic so that your article offers complete and
accurate information. Scholarly papers in computer science list
pages of citations, just as with any other field. Though technical
tutorials are held to a lower standard than original research, tech
writers should endeavor to substantiate ideas with the existing
literature and provide readers with accurate citations for further
exploration. Previously published work, source code,
documentation, research papers, conference proceedings, and
interviews can all add useful information and depth to your writing.
A Li de e e al a bee f c ed he a he ici y
and the helpfulness of the guide and of the tutorial. To
d ha ha e e dal f i e e ea chi g. Le
a e d c e i g K be e e e hi g eall
complex. You can only write about that from a point of
a h i if e ed i , in my opinion. Anyone can
i e ab K be e e , b if e ed i a d
understand the pain points of it, then you can write about
it from a point of authority such that a developer will
l ka a ial a d a , Tha k , hi ac all l e
some of my issue, or gives me a conceptual
de a di g f h I ca l e i e.
S e i e e ake he h le ea a d e ll e ea ch
e bjec ge he . I eall i -depth research, though
a he a e i e e ll a age da i g lib a and
some of the miscellaneous tasks that come in from the
open-source community. My team will all go down
different paths of a topic to start researching. Everybody

44
 pulls down the things and starts building applications if
i a la f ; if i a g a ming language they start
working with it. We read other tutorials, we read the
d c e i i g d c e a i , a d e ha e i -downs
with each other where we do knowledge transfers like,
Oh, he , I lea ed hi . Did k hi k ha
a ? We ha e i e ha e e e ha i g al g he
way and we try to solve them. What we create is an
internal knowledge base of documentation and links
ab he hi g ha e e e ea chi g.
O ce e feel like e e l c f able if i a e -
source project we try to talk to the maintainers we try to
look at the repo, we join slack channels, and we see what
kind of stuff is going on. We also talk to our internal
engineers just to see where they are. We show them
e f e ea ch a d e if ha e e n the right
ack a d he e ca a i i g. I d k if
knew this, but my internal team here at Linode is actually
really big, and the freelancing team is bigger than that, so
we have the resources to really spend time researching.
Angel Guarisma
Angel Guarisma has a whole team to develop content with, and the
le el f e ea ch ha he e f di ec l Li de
mission. As we investigate how and why to make a similar
investment in the research process for your own work, we explore
how to make the research possible for an independent writer.

3.1 Finding Sources

Ask any technical person to fix a misbehaving machine and the first
thing they will do is a Google search on the issue. As software
developers, our skills as Google power users make us practiced at

45
finding authoritative sources of information to use in articles. Just
like debugging, finding good sources is all about asking specific
technical questions.
You are often your own best information source, at least at the
beginning of the process. If your article is based on a prior project,
dust off that old source code and look at the documentation you
wish you had written a lot more of (at least, that is how it usually
goes for me). Extracting key snippets from the prior work will set
you well on your way toward a functioning sample application. If
your article is on a topic about which you have substantial prior
knowledge, create your own source by performing a knowledge
dump: just write down everything you can think of about the topic
in whatever order it occurs to you. This is different from an outline
because an outline defines the scope and structure of the writing,
while this document is solely an unstructured deposit of your
factual knowledge and insights.
Your market research from the idea validation step should be the
next place you look. It is important to ensure that you are reading
these sources to gain a general understanding of the field and
strategies for presenting information and not so closely that you will
inadvertently recreate the existing article.
Academic journal papers, conference proceedings, and other
scholarly work can be great sources for articles. While many of
these resources are hidden behind paywalls or in expensive
databases, you can often find free pre-print copies or email the
authors directly to ask to read their work. You can provide a lot of
value to your readers by reading broadly on a field and writing an
overview of a subject for the industry practitioner rather than an
academic audience. Read academic papers much more closely.
With your specific technical focus, extract useful ideas from

46
academic sources and be certain to maintain a list of sources and
cite them appropriately.
Academic sources lend extra credibility to your writing and, as they
are often perceived as difficult to read or not relevant to working
software developers, are a source to help you craft an article that
delivers a unique angle on a subject. Regardless of the sources you
consult, you will most likely need to create your own code samples
and determine new use cases for algorithms or practices that you
are researching.
Finally, review wiki entries, documentation, reference material, and
source code to round out your understanding of a given subject.
Do not be discouraged if these detailed sources make your article
feel incomplete. Bring in the most important aspects of the topic at
hand, but remember that a large part of the value you are providing
to the reader is outlining a path through a subject that gets them to
an understanding quickly. Direct curious readers to these complete
references at the end of the article, but do not fall into the trap of
a e i g a ch he h gh ali ie f a lib a API
reference or documentation.

3.2 Evaluating Sources

Not all source material is created equal. Disreputable sources can
deliver false information and harm your credibility as a writer.
Unfortunately, there is a lot of bad information on the internet, and
it can be difficult to verify that what you are reading is correct and
up-to-date.
I evaluate my sources through company filings and SEC
enforcement documents and stuff like that. If I write
about a criminal complaint, in some sense I will be
evaluating the credibility of the criminal complaint in my

47
 c l . I ll i e, Thi d e d e, ba ed
k ledge f he a he ld k .Al f
sources are just official sources and you can feel pretty
safe quoting them and using them for their intended
purposes, within limits. If someone gets arrested, you
have to say that they allegedly did whatever the
government says they did. But you can sort of rely on
that a lot. You can rely on it for the truth of it, but not for
the interestingness of the story.
I almost never make factual assertions based on what
someone tells me, either with or without attribution. Any
factual assertions that I make I do so because I know
them to be true from long experience or they are public
record. There are exceptions where there is a
c lica ed ic a d I i g de a d i and
people explain it to me. I will use that background
knowledge as part of my explaining, which I guess is kind
f ele a ca e beca e e alki g ab
ech ical i i g. If e a high-frequency trader and
you work at one of the six big high-frequency trading
firms and you tell me how the technology works, I tend
belie e beca e i a ech ical e la a i , a
factual assertion. Matt Levine
Fortunately, code is very easy to evaluate for correctness: just run it.
Style is harder, but I would generally recommend against including
third-party code snippets long enough such that architecture
becomes a concern. I prefer to reference API docs and other
sources and then create my own sample code that I am confident
in and exactly matches my needs for my article.
Be ech ical. Y d ha e be a f a e e gi ee
know how to write code, write scripts, read code, look at

48
 c de, a d be able edi i . Y d eed be a
systems engineer to be able to host your own
infrastructure, have a database, and build out small
agi g e f elf. Y d ha e be a da a
scientist to try out some machine learning algorithms.
But, that ability to try these things and wrap your head
a d he a d ead he d c e a i ha i e
for them puts you in a hundred times better place to
write documentation. Some of the best documentation
I e e e ead i i e b e le h a e
d c e ai i e . Wh ? I beca e he e li i g
that stuff day to day. If a writer can invoke that in the
same way that a fiction writer might travel to a city that
he e i i g a b k ab , j f de a d
it if e g i g be a ech ical i e i hi ld,
you need to eat sleep and breathe this world. Sure you
can read Hacker News, but every time those Show HN
things pop up, try the project out. Angel Guarisma
Your first line of defense is your own experience and rationality
because ideas are tricky to vet. Research is a great way to build a
solid tutorial, but if you are writing so far outside of your own
expertise that you cannot spot a false claim that directly relates to
the topic, you may want to reconsider what you are writing about.
Still, even knowledgable practitioners make mistakes or overlook
things. Thus, your second line of defense against misleading or
false information is the breadth of your research. If one source
disagrees with others, that does not mean that it is wrong. It does
mean that you should investigate both sides of the question further.

3.3 Interviewing
Interviewing is more art than science. Courtland Allen

49
Sometimes, a person is the best source for your article. For an
a icle I e f S a hi g Maga i e e i led Ada i g Agile f
Part-Ti e Tea , I a able i e ie fe add
voices of experience to my arguments. Interviews are one of the
key sources for journalistic writing. Early in my college career,
when I worked for The Scarlet & Black, G i ell eekl
newspaper, I performed multiple interviews that were often the
sole basis for feature-type stories. An interview is not necessarily
such an essential factor in a technical article; it is often easier to get
a couple of tweet-length quotes from busy people.
If I d de a d e hi g, I ll call he e le h
d de a d i a d a k he e lai i e . I ll
call a person who is a specific subject matter expert in the
thing, and there will be me who is good at explaining
complicated things, and between the two of us we can
ge e a e eliable i f ai . The he hi g i ha I
d ha e a eal a da e, if I eall d
understand something I i e ab i . Matt
Levine
There are two types of interviews: informational and quoted. An
informational interview is a discussion between you and a subject
matter expert designed to provide you with background knowledge
and context for your writing. They may not even be listed as a
source, but the interview will point you in productive directions for
your work. A quoted interview is like the ones in this book, where
you include quotes from the interview as part of the final work and
attribute said quotes to the interviewee. Both are useful, though a
quoted interview provides all of the benefits of an informational
i e ie a d le d he i e ie ee a h i clai .
However, it is often easier to get an informational interview,

50
especially from people who may not be able to speak publicly on a
given topic due to confidentiality agreements.
The purpose of an informational interview for me is to
just take notes on what they have to say. I often throw out
some of my initial working hypothese . I c e l
writing a piece about private equity in the software world
and so there are a number of people who I know and
respect who have professional backgrounds within
i a e e i . S , I aid he , S e f he hi g I
think are likely true ab ha I e b e ed e he
past couple of years are X, Y, and Z. What do you say in
e e ha ? I e ca e he a , Ye , ha i
a acc a e del f he ld. I e ca e he a ,
Y e ide ified he ,b d
understand the underlying cause. So let me tell you
about how private equity LPs would think about the
thing that you just talked about when you reduce it down
be . Patrick McKenzie
3.3.1 Finding the Right Interview Subject
Just like evaluating your source material, finding the right people is
the most important aspect of interviewing. There are several factors
to consider. You want someone well known enough to be
authoritative on a topic, but not so famous that they will not
respond to your query. For example, if I were writing about AWS,
I might reach out to a member of the documentation team that
wrote about the service, but not to Jeff Bezos. Another angle is
figuring out who can tell you useful information. Usually,
professors, independent creators, and open-source authors will be
less restricted by NDAs or other IP clauses than employees of large
c a ie , a lea ab ha c a k. Fi all , l k f

51
authors of in-depth relevant work in the field like books, journals,
and other sources.
The spotlight is on the guest, not on the interviewer. I
put a lot of work, especially recently, into trying to select
guests who I think will be entertaining and confident,
well spoken and charismatic, and easy to listen to, and
who actually will have relevant things to say that are novel
and that the listeners will find insightful. A lot of
i e ie e d f c a ch g e elec i . I
really easy to focus on what you can do as an interviewer
to get the most out of the guest, but I really think ha
only maybe twenty or thirty percent of the equation.
Courtland Allen
As with publishers, personalized cold email is a great way to ask
people to do an interview. Keep the email short and the request
reasonable, both in magnitude and timeframe. When I am going to
interview someone, I make the interview request early in my
writing process to allow for scheduling. The exact nature of the
request will differ based on what kind of interview you are asking
for, but in general you will explain yourself, the project, and why
you want to talk to them in particular, all in a few brief paragraphs.
It may seem daunting at first, but once you have done it a few times
it gets easier, and I am constantly and pleasantly surprised by how
generous people are with their time and wisdom.
3.3.2 Synchronous Interviews
The traditional interview is real-time and by voice. Usually, it is
going to be by phone or video call, but occasionally they are in
person. All eleven interviews I conducted for this book were
synchronous interviews. Synchronous, or real-time, interviews
generally accommodate more questions and require a smaller time

52
investment per question from the interview subject. In my
interviews for this book I generally got through eight to fifteen
questions in twenty-five to fifty-five minutes. You will not need that
much interview content for a single article. As the interviewer,
invest your time in good preparation to make the interviewing
process smooth and allow for easy transcribing and editing after the
interview to extract the quotes you need.
Here are three assorted tips for synchronous interviews:
1. Run multiple independent recording devices.
2. Include scheduling information in your first request.
3. Set aside sufficient time to transcribe the full interview.
Multiple recording devices provide redundancy in case of
equipment failure. Including your full availability in the first email
helps minimize back-and-forth scheduling. It may sound obvious,
but you want your request to be as easy for your chosen subject to
accommodate as possible, so include a wide array of options to
ack ledge he e i i g de a d i e ie bjec i e.
Transcription is a difficult task; it usually takes me four focused
hours to transcribe one hour of audio. A proper ergonomic typing
setup and some sort of play-pause foot pedal make transcribing
much easier.
3.3.3 Asynchronous Interviews
Asynchronous interviews are simple: you send an email with
questions; you get an email with answers. However, asynchronous
interviews require work from your interview subject, as you are
essentially asking them to write part of your article for you, for free.
To adjust for that, ask far fewer questions. Three is a stretch. After
the same opener as a synchronous request, include the questions
directly rather than your scheduling information. If the interviewee

53
responds to your request for a synchronous interview by offering
an asynchronous one, feel free to ask a few more questions as they
have volunteered written answers. Either way, follow up on any
answers that are unclear and pursue interesting leads just like you
would in a synchronous interview.
3.3.4 What to Ask
Do your research and make sure that you are asking your interview
subject relevant but fresh questions. The higher profile or more
prolific your subject is, the harder and more important the task. If
you get a busy person on the phone, the worst thing you can do,
with the possible exception of insulting their mother, is to waste
their time.
I wanted my interviews to stand out from other
interviews. I wanted my website to be particularly
ca i a i g, I ade e ge e e b d e e e
numbers. That meant that nine out of ten people that I
a ked i e ie aid , beca e e le d a
share their revenue numbers. But I only interviewed the
people who said yes. Courtland Allen
Here is a true story of this situation taken to the extreme. In my
first semester at Grinnell College, the college was invited to send
twenty students to join similar groups from six MBA programs on a
day-long trip to learn about Berkshire Hathaway, an experience
highlighted by a two-hour luncheon and Q&A session with Warren
Buffett, arguably the greatest investor of all time. That same year, a
private version of the same lunch went for almost three and a half
million dollars in a charity auction. At the time, I was interested in
finance and I knew that I had to go.

54
The problem was that I was just two months into college and
competing against almost a hundred older, more experienced
students for a spot. The application had a few essay questions, the
i a f hich ead: Wha h ee e i ld
like a k Wa e B ffe ? I k e hi a cha ce a d
out from the crowd. Warren Buffett has appeared in hundreds of
interviews over the course of decades. Many of these questions and
their answers had been compiled on www.buffettfaq.com, to the
tune of approximately one hundred and seventy thousand words,
or two full-length novels. I reviewed all of that information in a
frantic weekend and constructed three questions that I could say,
with reasonable certainty, were original, at least in some aspect. I
achieved this through a combination of probing one level deeper
into established answers and applying new information to
contextualize old questions. The story has a happy ending: I was
selected for the trip, and the selection committee specifically noted
that the work I had put into the questions was the primary factor.
In the course of interviewing for this book, I used the same
strategy, though with a less frenetic time investment per interview
subject. Before writing questions, I read as much as I could from
each i e ie bjec b d f k. I c ea ed e i b
eeki g f he de ail bjec bli hed k a d blic
statements, applying present-day context to work my subjects did
earlier in their careers, and asking standard questions while
acknowledging their frequent use. Your interview subjects will
appreciate a similar, thorough preparation.
My first rule of thumb for myself at least is to try to come
up with questions that allow the other person to talk for a
while, that allow them to showcase their expertise, that
d eall e i e e ee he [i e ie ] i a
particular direction. Courtland Allen

55
One tip is to only ask one question per question, but be ready with
follow- e i he a e ic. Whe I a e e i
e e i , I ea ha ce ge a e i a ki
speaking, stop talking and let your subject respond. This ensures
that your interview subjects do not miss (or dodge) bits of a multi-
part question. Also, it allows you to adjust the conversation
trajectory to keep the interview on course. As you will see in the
transcripts in Appendix A, I mostly follow this rule. Where I
deviate, I would circle back to restate part of my initial question. If
you have to do this often during the interview, it decreases the
efficiency of the conversation, which may reduce the amount of
i f ai ge d i g ce li i ed i e.

3.4 Citation and Rights

This is not the last time I will say this: I am not a lawyer, and the
following is not legal advice. Also, this section is written from an
American perspective, and laws may be materially different in
different countries. Copyright law is a serious topic and it is
important to have a working understanding of the areas that apply
to your work as a technical content developer. Chapter 13 contains
a more thorough discussion of copyright. Here, I am going to cover
de a di g f h e he e le ork respectfully
and lawfully. You have two big advantages in attempting to do so
hile i i g ab f a e: i d fe e e f e
source with explicit licenses and the general concept of fair use.
Most code on the internet intended for other people to use comes
with an explicit license. Repositories often include a license.txt file
in the root directory; check that to determine if you can use the
code. Open-source licenses allow the copying of code with
attribution. Commercial open-source licenses, like MIT, Apache 2,
and BSD, allow the reuse of the code commercially. Most code

56
that you would want to reference in a technical tutorials exists
under open-source licenses. However, some open source licenses
are so-called copyleft licenses, which require derivative works to be
licensed under the same terms. Avoid all code under copyleft
licenses when writing for clients.
Fair use is a broad and nebulous concept in copyright law.
Essentially, it means that you can copy whatever you want, as long
as it is fair use. Unfortunately, there is no single definition of fair
e. I e c age ead Rich S i ii g he bjec
S a f d U i e i Lib a ie eb i e. I e e ie ce, c -
sense citation of reasonable excerpts of other work is not frequently
a source of trouble in our industry.
Unlike academic contexts, there is no formal citation style
common to technical articles, no APA or MLA or any other
format that may be familiar from university papers. Depending on
the client, citations will probably look like either footnotes or inline
hypertext links. What is important is making sure that your readers
can trace the origin of third-party facts and ideas so that they can
use your article as a base for further research and you have given
credit where credit is due.

//TODO
1. Choose one article that you pitched in Chapter 2 and are
interested in developing further. Perhaps a publisher has
already replied to you and wants to publish one of your ideas.
If not, pick the article you feel best about.
2. Wi h he a icle i le a d de c i i f Cha e 1 i
hand, take a few minutes to write down everything you can
think of on the subject. If the article is based on a project you
have done, review that code.

57
3. Thoroughly research your topic. Read widely; consult other
articles, documentation, and academic papers. Remember to
keep track of every source you visited so that you can link to
the relevant ones in your final article.
4. After you have completed your research, if you think you
need some extra material, try to find an interview subject.
Send two or three requests, but do not wait to hear back
before you begin writing.

58
Chapter 4: Preparing to Write
You could start writing your article right now. After the research
phase, you should have a decent idea of what you are writing about.
However, there are two steps that you should take to make the
writing process more achievable. Outlining your article moves you
from idea to hypothesis and helps you build a scaffold. Writing
sample code tests that hypothesis. With an outline and sample
code in place, you will have a roadmap for writing with a clear
understanding of where you are and where you want to end up.
You will even have a map to get there.
Your technical skills will be essential in both steps. Outlining relies
on your ability to take a large idea and factor it out into discrete
components. You are already good at writing code, that is why you
have an idea for a technical tutorial in the first place. If you have
jotted down a todo list and coded a project before, you have
everything you need to complete these steps ahead of writing.

4.1 Outlines
Creating a detailed outline of an article is my favorite part of the
writing process. It allows me to think about the interesting
questions of the article hile ab ac i g a a he i le e a i
de ail fh ac all e ec e he i i . A g d li e
will present three key pieces of information about the article: its
audience, its structure, and its contents.
I think that technical writing is really expanded outlines,
e ch, a d i he a e he e eadi g c de.
Y d like c de be ell d c e ed, i h a l
of sections, a lot of break-up in your code, and I think
ha j he e al del f ech ical k. S I

59
 think that it makes sense that it transfers over to the
content side. Chris on Code
At this point in the process you have a general topic idea, a short
description, and a potential title from the pitch that your publisher
accepted to serve as a starting point. You should also have a
general sense of the subject matter from the research phase. Taking
time to figure out the structure of your article will make actually
writing it much easier.
Here is the outline of the article in Chapter 10.
Introduction (300 words)
Can computers make art?
Is meaning inherent in text or projected by the reader?
Bot or Not
T PhD d eed f hi a icle: E gli h a d
Machine Learning
Three of text generation: naive selection, Markov
chain, GPT-2 (example of neural networks) for writing
poems
Why Poetry (200 words)
Generating text is hard because of parts of speech
Generating some kinds of poetry is even harder
because of rhythm, rhyme, and structure
Because of the many different types of poetry and
ways of interpreting them, it may be simpler to create
passable poems than prose
An Algorithm is only as good as its input (200 words)
Quantity, quality of input data
more advanced method require more data, like a
racecar requires high-end fuel

60
 Naive Selection (200 words + example poem)
Shakespeare example
minimum coherent unit / line level of abstraction,
enormous number of outputs
Examples & analysis (example + 100 words)
Markov chain (200 words + example poem)
How does a Markov chain work
examples and analysis (example + 100 words)
Neural Networks (200 words + example poem)
GPT-2: training and overview
GPT-2 not released into the wild
Examples and analysis (example + 100 words)
In Conclusion (200 words)
Can computers write poems? Maybe. Does this mean
the end of poets? No.
Other applications of text generation
Further Reading
All links from research step
One danger of presenting an outline in this book is that outlines
only need to make sense to the author and sometimes the editor.
Most of this outline is not clearly written. Similarly, your outline
solely exists to help you write. Do not tie yourself to your outline; it
is only your first attempt at structuring the information in your
article. During the writing process, you may discover a better way to
present the information. If you do, pursue it.
There are a few key components of this outline that helped me
write the example article. First, every section is present, in order,
with approximate word counts. These word counts are not really
targets. They are there to help me remember the scope of each

61
section. As sub-points, I have a phrase or two describing what I
would like to cover at a paragraph-by-paragraph level. This outline
constrains the information from the research step, clearly defining
what is relevant to the article and what has been cut.
4.1.1 Audience
What does your ideal reader already know, and why are they
coming to your article? These two questions are everything you
need to define your audience. Be specific. If you can, model your
a icle ideal eade ff f e e k f k
school, or at least a role or archetype.
I started out writing at a real financial industry blog. I
thought of my ideal reader as a first-year analyst at an
investment bank: someone who is 23, has a background
in finance, knows what DCF stands for, has a basic idea
f he l ,b d e k al fc lica ed,
specific details that I can explain. Matt Levine
Matt Levine has had years to gain an understanding of his audience
(see Appendix A for his full explanation of his audience). It takes
time to figure out who is reading your work and what they hope to
get from it.
Background knowledge assumptions are important for the
structure and cohesion of your article. Do you need to teach your
reader how to install the programming language that you are using?
Do your readers know linear algebra? Are your readers using the
command line? Some of the answers will come from your
knowledge of the audience of the publication you are writing for.
The rest you will have to decide for yourself. These are
fundamental decisions that determine the pace and scope of your
article. Ultimately, no matter what you decide, you will be

62
eliminating some subset of readers; however, that narrowing of
your audie ce e e i e he a icle ef l e he
people for whom you are writing. Do not be afraid to write for an
advanced readership for the right publisher, even if it means your
work misses a larger beginner audience. On the flipside, beginner-
and intermediate-level articles are often in high demand.
F e a le, if e d ci g a c e ha a ge ed
a ab l e begi e , i g a h ge a die ce beca e
most people are beginners. There are always more
beginners than there are intermediate or expert people,
c e ha a h ge a die ce f e le h a e
really that serious. Courtland Allen
J a i a i de e i i g eade g al i c i g
your article. If your reader wants to quickly grab code samples,
keep your text short and keyword-heavy. If your reader seeks a
deeper understanding of a narrow topic, take your time and
explore every path through the niche. You will make a number of
decisions optimizing your writing for a particular set of users,
deliberately determining your readership.
I was writing for myself when I was learning. I just aimed
my writing at the kind of person that I was. I was a web
designer who was worried about programming and
h gh I c ld be a ga e . I fel e
comfortable with browsers than command lines. I
a ed ee he e l i he b e . Tha h
coding felt real as opposed to seeing it in a text editor or
a command-line interface. In terms of knowledge, the
other thing that I really wanted to focus on was assuming
my readers had no programming knowledge. There are a
lot of tutorials out there that assume that you know what

63
 a Model-View-C lle i , b I did a defi e
those terms because Hello Web App is really about
helping you build a web application. Tracy Osborn
While identifying your audience is important, do not spend more
time planning than writing. For just one article, it is okay to write
for a very narrow audience. If you have more to write, you may be
able to place a series of articles with one publisher or aim different
articles on the same topic at readerships with differing skill levels.
When writing something longer than a 2,000-word article, take
more time to make sure that it is something people will want to
read.
4.1.2 Structure
If your K 12 education was anything like mine, you wrote a lot of
five-paragraph essays. The five-paragraph essay is a rigid formula in
which you construct an argument with an introduction that
cumulates with a thesis statement, followed by three supporting
body paragraphs with topic sentences and substantiating details,
and ending with a conclusion that restates the thesis. While this
formula is suitable for cranking out papers on Pluto and the
American Civil War, your technical writing will benefit from a
different structure.
A lot of pieces in [our] genre are heavily improved by
ha i g a be e a a i e f he iece ha j e
f a e X c bi ed i h idea Y. Pe le e d
de al e ba ic i f a i . Sa ee ie
H e WebS cke i h NSQ e e, he e
WebSockets are a way to get information from a server
to a client browser asynchronously without the client
having to request the additional information, and
NSQueue is a queuing technology. If it is just

64
 WebSockets plus NSQueue, a lot of people will assume
that is a one-on-one level article. In fact, that is plausibly
an article that an engineer could write in their first year of
being a professional engineer. For me, it was an article
that I spent days of my life at my last startup working on
beca e I did ha e acce i.I a ki g
the article; I was working at the intersection of those two
technologies and banging my head against the wall.
Patrick McKenzie
Y a icle c e h ld f ll he a a i e f he ble
you are trying to solve, interspersed with appropriate amounts of
technical detail.
The better way to write that article is to start with a
i a i g e ca e like a chi ec i g a eal-time chat
a a d he g he ech ical de ail ab i.W d
like a chi ec e a d eal- i e a e high-value words
within the community. Because a chat app is a use case
that anyone can quickly wrap their head around, you
ha e a c ce al f a e k f de a di g, Oka ,
what is the thing we are actually trying to do with
WebSockets here and why does it actually matter? Why
ld e be i g NSQ e e? Patrick McKenzie
You should have an introduction, and you can use it to motivate
the solution you will be building and discussing. You can even
include some personality to get the reader comfortable with your
voice. However, you must do all of this as quickly as possible,
preferably in fewer than two hundred words or ten percent of the
article length, whichever is shorter.
After the introduction, list any important prerequisites or
installation steps that the user should take. Provide explicit

65
configuration instructions for whatever systems you will be using
and ensure consistency in environment details like language and
package versions.
The general information architecture that I use for
iece i eeli g back la e f he i a bi a il
deep. You start with that super high-level explanation of
the goals of doing this, and then you continue
unwrapping the onion one layer at a time until you get to
the very nub of i he e e h i g e le ac al
code snippets. Patrick McKenzie
Start at the beginning and follow the steps for programming until
the end. A single linear thread is the best form for a technical
tutorial. For an informative article, you have more flexibility in
structure, but should stick to simple narratives. Remember to focus
on establishing the problem, demonstrating its importance, and
providing a solution.
Y ha e be able e lai he ble e
l i g fi . R bbe d cki g i his classic technique
where you take some inanimate object and you pretend
i a e a d e lai he ble ha
inanimate object. A lot of times, not all of the time, but a
l f i e ll ac all fig e i beca e he
process of talking to this inanimate object and just
explaining the problem in some rational way gets you
pretty much to the solution. Jeff Atwood
For the conclusion, keep it short and avoid restating information.
Instead, discuss further avenues for the users to explore and link to
interesting adjacent concepts that were outside the scope of the
tutorial.

66
4.1.3 Contents
The outline is one of several steps in the writing process where you
decide what to leave out of the article. This may be background
information that you determine your readers do not need,
advanced concepts outside of their current reach, or just extra facts
that do not contribute to the core tenets of the article.
Your outline should be as detailed as you need it to be. I focus on
the architecture of the implementation, key sources that relate to
specific components, and important connections that I want to
highlight for my reader. Most of the time, there is a point in the
li i g ce he e I feel a h gh I ha e c acked he
article, or discovered the crux of the subject around which the
entire piece will revolve. This could be a central implementation
detail, a technical insight, or a broader structural element that gives
me confidence that I can write what I am setting out to write. For
me, this feeling comes when my outline answers three questions:
1. What information is in scope for the article?
2. What examples will convey that information?
3. Why will the reader care?
While outlining the article, write approximate word counts on each
section header and make sure they add up to a reasonable
approximation of your target word count. These are rough
estimates, so do not place too much weight on them. The correct
length for your article is the shortest number of words that
effectively conveys your message with style and personality. That is
not to say that you should relentlessly focus on lowering your word
count; rather, you should focus on completing the article without
using entirely extraneous material. Publishers usually have a
general idea of appropriate article length. The most frequent word
count I pitch or am assigned is two thousand words. I have found

67
that if I deliver a complete article within fifty percent above or ten
percent below the assigned target, and if the article is in fact
complete, clear, and accomplishes the designated task, the
publisher is satisfied.
4.1.4 Cancelling an Article
I do not have the statistics to suggest how often this happens, but I
am still confident in saying that no writer goes from idea to finished
piece every time. Some ideas have to be discarded, or at least put
aside, for any number of reasons. The trick is identifying issues
with your work as early as possible in the process so that you can
adjust the scope or work with your editor to adjust the existing
topic or pick something entirely new. I have been in the
uncomfortable position of cancelling articles that were half written,
that were outlined and accepted, and that were pitched. I have also
had to delay articles by a month. Obviously, I am not proud of this,
and it is not a good habit to engage in if you want to maintain a
professional reputation. However, I have found editors to be
incredibly understanding of the nature of the writing process and
sympathetic to the fact that not every idea, even if it seems good at
the start, makes it to the finish line. Do your best to make an article
work, but communicate difficulties early. A good outline should
help you to figure out whether or not your topic is viable for this
publisher at this time.

4.2 Sample Code

Code samples are one of the most precise and concise ways to
explain technical information. The blessing and the curse of code
blocks in articles is that they communicate exactly what the author
means to express to the computer, but no more. Thus, sample

68
code is an important component of many technical articles, but it
rarely stands alone.
I believe programmers learn code by writing code. The
most productive way to start writing code is to have
examples. There is basically no original code in the
ld; i s all some variant off of the family tree of code.
I wanted to have a way of documenting software that
e b aced ha . A ch a ible, e h , d ell.
Mark McGranaghan
You will likely write more code than you include in the article. I
tend to go through an experimental phase at the beginning of the
coding process where I try to get things working without attempting
to optimize or beautify my code. Once I have a solid structure, I go
back and revise my code as needed. Furthermore, some systems
call for prepared data or other formatted input; the process of
creating that is outside the scope of most articles. In these cases,
simply omit the irrelevant code or provide a link to a repository
where interested readers can track it down.
When I was building a side project, I would try to
document the side project, as in I would try to outline all
of the steps for a course or a series of articles while
c ea i g he ide jec . I d al c ea e a ide e , like a
vanilla repo that was going to be built for the tutorial, and
I found that was just way too much context switching
between an actual application and a tutorial application,
especially when the code overlaps so much. So I stopped
d i g ha . I d c ea e a a le e a e,
although I do keep outlining all of the steps I think it
ld ake. I hi k ha g d e gh, e eciall
because you can go back into that live application and

69
 start picking and choosing snippets after that. Chris on
Code
While developing, extra-frequent Git commits can help you track
and later reconstruct your progress. Overall, I advocate for version
control, Git in particular, and recommend its use for all technical
content projects. Not only does it help you track and recreate your
progress, but it makes collaboration, updates, and sharing of your
sample code and other article-adjacent materials easy.
All writers should be pretty proficient in using Git, and a
lot of people think that learning how to commit
something and push it up to the master branch is
enough. That h I ha i g hi e ce
thing. When you contribute docs to open source, you
can make these mistakes and people will help you
through it. You will in turn learn how to use version
control, or Git specifically. That, while not directly
related to technical writing, is what I think the whole field
is moving to right now. By being really good at Git,
e able c ib e jec . Y e able hel
tons of people and become more technical yourself. By
d i g ha ei e echnical and can write
better how-to guides and tutorials. Angel Guarisma
Whenever possible, code should be complete and executable with
imports and all other context necessary to allow your reader to
copy, paste, and run the code seamlessly. While this context can
lengthen code snippets and may eventually feel repetitive, it is the
best way to ensure that your reader can access the sample code at
any point in the article and use it for their own purposes.
The exception is when you are working with large, multi-file
projects in frameworks like Django or developing an app for

70
Android or iOS. In these projects, there are dozens of
configuration or other files that are full of automatically generated
boilerplate. In these cases, use your best judgement in providing
sufficient context that the reader can identify where to use the
sample code, but do not copy in needless boilerplate. Projects
using large frameworks benefit the most from the simultaneous
distribution of a repository containing a full, runnable version of
the final product that the tutorial constructs.
We decided that one of the most daunting things with
AWS somewhere that we could provide value is that
c ea e a AWS acc a d he i e ha d
figure out how to do things properly. The official
documentation is very advanced with lots of details.
The e i gle e i j f ll . We c ea ed a
very detailed tutorial where the final result was a
production-ready setup. We worked backwards from
there; we had the final results and then we spent some
time thinking about the right checkpoints to create
chapters that made sense and to not dump everything on
the reader at once. We thought about how to make it not
too daunting by breaking it up into small pieces so that
the reader would feel like, Oka , I a i gf
scratch. I create a new account, make something where
you can see it and improve it a bit and improve it a bit
a d c i e like ha . Daniel Vassallo
For an article, good clean code is concise but easy to understand;
you should optimize for readability first. Code golf, or the practice
of attempting to solve a solution in the minimum number of
characters, has no place in sample code, and neither does pointless
verbosity. Your code should follow logical architecture and best
practices, but unless you are writing about performance or for an

71
advanced audience, it is better to have code that is fast to read than
code that is fast to execute. Finally, lint your sample code before
including it in the article lest your readers believe it wrong on the
account of IDE warnings.

//TODO
1. Consider your audience. Who do you imagine benefiting
from reading your article? What will they be able to do after
reading the article that they could not do before? Write this
down to begin your outline document.
2. With your research from Chapter 3 in hand, outline your
article. Focus on the structure and order of the content and
make sure that everything you plan to write about is relevant
to your audience.
3. If you are creating a tutorial, develop the sample code. At this
point, do not worry too much about writing code for an
article. Program as you normally would, but be sure to note
down the steps you take as you take them.

72
Chapter 5: Writing for Software Developers
I ha e ead a be f b k ab i i g, f Na ha Ba
Authority S e he Ki g On Writing to recent editions of
W i e Ma ke . In my experience, books about writing (except for
style guides) tend to dedicate only a small fraction of their length to
what happens when the writer is actually writing. Until I sat down to
write my own book about writing, I found this disappointing. How
could you write about writing without, well, writing about writing? It
turns out that there are two primary causes for this widespread
phenomenon. First, writing is a very individual process that is hard
to describe in the abstract or teach conceptually, unless you are
addressing specific aspects like grammar or usage. Second, most of
what happens around writing is the opposite: easy to describe, but
not intuitive to figure out. Thus, I am joining a long tradition by
dedicating only one chapter to writing.
I often get asked about my writing process, and I also ask
other writers who I respect about their writing process.
The writing process tends to be intensely personal to
each i e , a d I d ece a il k ha i i
ge e ali able. I d i e i he a ha e f
favorite writers write, nor have I been able to teach
people successfully how to write in the way that I do. I
have generally been unable to operationalize things that
people have attempted to explicitly instruct me on with
respect to making my writing process more effective.
Patrick McKenzie
The writing process is the hardest part of this whole endeavor.
David McCullough, a Pulitzer Prize and National Book Award
i i g a h , fa l aid, W i i g i hi ki g. T i e ell i
hi k clea l . Tha h i ha d. Ada ed f ae

73
engineering language, writing about programming forces us to
operate at a different level of abstraction than we normally do while
programming, and to do so along an axis that is perpendicular to
the levels of abstraction that we more regularly traverse. However,
sufficient work on outlining and, when needed, sample code can
make the writing itself feel achievable.

5.1 The Actual Words

With completed sample code (if appropriate), research, and an
outline completed, your actual writing process should feel steady
and achievable. It is still the hardest part, in my experience, but
with enough time and practice, it should begin to feel like a regular
part of your work rather than a recurring miracle.
The testing and gathering phase continues for a while,
il I feel like, Oka , i b ad ke I k he
a ach I g i g ake hi iece. The , I ge
the extremely non-replicable portion: I sit down at a
desk, drink a lot of coffee, and write like a man
possessed for six hours. Patrick McKenzie
For a book on writing, I have been remarkably short on
metaphors. I seek to rectify this oversight by asking you to imagine
that you are building a bridge for your readers to cross. On one
shore stand your readers, secure in the land of existing knowledge.
Your task is to construct a safe passage over a wide strait of
uncertainty to the island of new understanding.
Now, you cannot simply lay planks for miles and hope that they
stay rigid. To cross wide spans, you must construct additional
pylons to support the overall structure. Sample code, cited facts,
diagrams and images, and other discrete certainties are the pylons
spanning the strait. The outline determines the order and distance

74
between these structures. Your job in the article itself is to span
each gap with explanation and intuition. Matt Levine, for example,
writes his newsletter using block quotes as pylons:
A lot of my audience is in some way technical and is
interested in the technical details of these things. The
block quote is the equivalent of the code; they want to
see the guts of the thing. My commentary will be some
sort of deep structure explanation or some sort of joke or
e hi g, b I g i g ell he g i a a ha
is more accurate or specific than what the guts are, so I
might as well just show them. Again, people can skip it.
People who are interested in the technical details are
going to read the block quote and people who are
looking for the jokes can skip right over the block quote
a d i he j ke . I a ice a eg e he
readership. Matt Levine
The two ai l f a k a e he e i Wh a d
H . Bef e each l , e abli h h i i eeded. Af e each
pylon, describe how it functioned to get you closer to the
destination. Motivating and explaining code helps avoid the trap of
simply repeating yourself by explaining concepts in code and again
i d . O he cla ic e i f j ali , Wh ,
Wha , Whe , a d Whe e, a e all be a e ed i he
introduction and conclusion. In our metaphor, these are the on
and off ramps of the bridge.
5.1.1 Craft and Style
At the craft level, there are a few things to keep in mind. These are
general heuristics that make sensible defaults. You will know when
it is right to deviate from these guidelines. The most common
ea de ia e i c f a gi e bli he yle guide.

75
I prefer to write in the first person (I write this) and second person
(you write that), as I have been doing for this whole book. I
especially like the first person plural (we do this, we now
understand that). To my ear, this establishes a conversational tone
and familiarity that mimics explaining a concept to someone one-
on- e. I a d e abli h di i c cha ac e i e .A a
general rule, I try to avoid using the third person (one writes that).
However, for articles about more abstract concepts, I will
sometimes write in the third person. This helps when synthesizing
and analyzing sources or conveying other concepts that I do not
have direct experience with.
Default to present tense. Of course, use the past tense to describe
the past (Python 3 was released in 2008) and the future tense to
describe the future (Django 3.0 will be supported through 2021).
Otherwise, stick with the present tense for the bulk of most articles
because the reader is following along with your tutorial in the
ee e . Th , he iei ci like c he
following HTML into index.html, a e de c ibi g he ac i
that they are taking in the moment that they are taking it in.
Most writers and editors tell you to avoid passive voice. Passive
voice is where the object of a sentence is being acted upon by the
subject. In active voice, Sarah writes the program, in passive voice,
the program is written by Sarah. In general, I agree with this advice.
In technical communication, it is critical to identify the correct
cause and effect in a system. Active voice combats ambiguity.
Keep your syntax and usage accessible but interesting. Do not
throw around ten-dollar-words just for the sake of it, but be precise
in your diction; if there is a word that expresses your exact
meaning, use it. As the same time, be generous to your reader. If
you suspect that the precise term may not be familiar to your

76
reader, offer a definition of the word or acronym after you use it
for the first time in your article. Keep your target reader in mind;
define any terms, technical or otherwise, that might trip them up.
F e a le, i he a icle i Cha e 8, I defi e ia bic
e a ee b a e ha eade k ha URL ea .
Vary your sentence length. A long sentence can be helpful in
expressing a complex connection, its multiple clauses conveying
substantial detail. Be careful not to sacrifice readability to length.
Solid, clear prose with a bit of flair where appropriate will establish
your presence as a writer and will communicate your ideas
effectively.
I hi k he e e fi e li e be ee ch e ali
and just enough personality and almost none. Some
people will use their personality and apply it to the
article, but then it takes away from the actual content.
The e a l f fl ff ha I e ef g e -author
articles, and that just goes to skimmability. People want a
couple lines of personality and then they want to get to
the actual good parts of the technical stuff of the article.
Definitely try to test out how things are. When I say test
out, I mean definitely try different writing styles, push it
out, see what the community thinks and get feedback
f ha . W i i g i ch a d a ic hi g: i a gi e a d
take between you and your readers. Just see what your
readers like and go from there. Chris on Code
5.1.2 Voice
There is a perfect secret for developing a clear, natural voice in
your writing. Using this technique, you will learn to channel your
personal, inimitable style into your writing. I have not yet mastered

77
this approach to voice. This mystic wisdom is easy to write but hard
to read.
Here it is: there is no point in attempting to develop a voice in
writing because you already have one. That is the secret. That does
not mean that you should not pay attention to how your writing
sounds. When evaluating your own work, look for phrases that do
not sound like something you would say in real life. This is what
needs to be fixed for your voice to naturally reveal itself over time.
Imitating other i e le i a i c edibl ef l e e ci e f
developing your craft and specific techniques, but outside
influences should melt into the background that you bring to each
written word. While this is a process that will happen, it does take
time and consistent practice.
If j ief blica i e e da , ll de el
your own voice naturally. My perception was that
blogging, writing on the internet, was like writing an email
f ie d . The e eall be e a ie
naturally and in a conversational style that sounds like
yourself than thinking about your writing as writing an
email to your friends. I had experience writing emails to
my friends at Goldman Sachs and making jokes and
trying to be funny while also assuming a pretty high level
of specific financial knowledge. That was a useful
experience to draw upon when writing for a publication.
In fact, I remember six months or a year into my job at
Dealbreaker having dinner with some of my Goldman
friends and one of them saying, Y k , eall
d like . Y did ed d like
when you started; now you sound like yourself. I read
a d I like eah, ha Ma . Tha a a alida i g
moment for me. When I write, it clearly is a persona, but

78
 the main aspects of developing a voice is not so much
developing that persona but stripping away artifice and
hi g ha e ied ick f el e he e ha
the writing sounds more like your conversational style.
Matt Levine
More than a byline or author bio, your voice is your signature on
the page. It is why teaching writing is so difficult. It is why you like
some authors more than others. It is more than just words, it is
how those words occur to you that matters. Practice, but trust
yourself. Trust your voice.
F diffe e ia i g elf i i i g, I hi k i eall
just about finding your own voice. That comes with
practice. I graduated from Iowa State University. At Iowa
State I blogged for the university on cyclonelife.net. I had
to write three or four blogs every week for them and so it
was really just a matter of practice. The more I wrote for
them the more I developed what my tone sounded like
a d ha ice ded like . I hi k ha ha a
l f e le a e he i a d , he e like, Ah, ell, I
a bl g, b I d eall ha e a ice. I eed
de el ha ice. I hi k ha j c e i h i g
pen to paper, writing stuff down, and actually writing out
blog posts and developing it over time. Cassidy
Williams
5.1.3 Your Writing Practice
Each time you sit down to write, focus your attention on one
di c e e a f a icle. If he a icle ec i ae big
tackle, break them down. With only your outline, research, and
relevant code in front of you, write a section in simple,
straightforward words. Try not to get hung up on making the

79
language pretty or elaborate, just get the words on the page. It will
be much easier to adjust your work when you have a piece to edit.
You know if you are a marathoner or a sprinter, and you can set
your writing schedule accordingly. Planning to write a little bit of
the article, or one plank of the bridge, at a time will take some of
the worry out of writing. Plan your writing time; these writing
blocks do not need to be long, twenty to forty-five minutes, but they
should be as sacrosanct as any other appointment on your
calendar.
In his booklet Learning Technical Writing Using the Engineering
Method, Professor Norman Ramsey presents eight practices of
successful writers, which he has generously allowed me to
reproduce here.
1. Pause mindfully, frequently. Mind your body, thoughts, and
feelings and the stage of your work.
2. Write in brief daily sessions. Ignore the common myth that
successful writing requires large, uninterrupted blocks of time
instead, practice writing in brief, daily sessions.
3. Focus on the process, not the product. D ab he
size or quality of your output; instead, reward yourself for the
consistency and regularity of your input.
4. Prewrite. D be af aid hi k bef e i e, e e j
down notes, diagrams, and so on.
5. Use index cards. Use them to plan a draft or to organize or
reorganize a large unit like a section or chapter.
6. Write a Shitty First Draft . Val e a fi d af beca e i
g ea b beca e i he e.
7. D ab age li i . Write the paper you want,
then cut it down to size.
8. Cut. Plan a revision session in which your only goal is to cut.

80
Keep these principles in mind as you develop a steady, reliable
writing practice. As I learned while writing articles and learned
again while writing this book, time in the chair is the only way that
words get written.
5.1.4 Markdown
Write in Markdown. Unless you are a wizard with LaTeX or your
client specifically requests a different format, Markdown is the
smart default: you can write Markdown in a different buffer of
whatever editor you are using for your sample code; it has all of the
formatting you need for both words and code; it is compatible with
version control; and it is interoperable with most publishing
systems, or at least it is easily convertible into a format that is. If
you do not know Markdown already, it is among the most powerful
tools you can learn in five minutes.

5.2 Graphics
As you are writing, you may realize that your words and sample
code would be even clearer if supported by graphics. Screenshots,
pictures, and diagrams are a supplement to, not a replacement for,
good writing and complete sample code. Make notes to yourself
while writing your first draft as your realize a need for any form of
graphic. Once the draft is complete, move on to creating them. If
you have trouble finding or creating graphics, reach out to your
editor. They can help you with the process, and sometimes will
find or make graphics for you.
There are three kinds of graphics that I use in articles: screenshots,
pictures, and diagrams. They each have their own use cases,
advantages, and drawbacks. Graphics are a great way to break up
walls of text and keep readers engaged, but when overused can
overburden the writing.

81
Sc ee h f Cha e 9 T ial
Screenshots are useful when you are creating a tutorial on building
or interfacing with anything that presents a graphical user interface,
be it an app or website. A screenshot of the full system at the
begi i g f he a icle ca i e a eade i agi a i . A fe
screenshots at key checkpoints can help readers ensure that they
are following along in their own implementations without issue. Pay
careful attention to ensure that your screenshots match the actual
state of the system as developed in the article rather than during the
experimentation phase in sample code writing. When using
screenshots to guide your reader through an existing user interface,
make sure you are consistent and complete in describing the

82
actions that they should take and the feedback they should receive.
In all cases, it is useful to annotate screenshots by circling or
highlighting key elements for the reader to focus on.

Pic e f Cha e 10 A icle ( Macbe h: Fi F li b Ma

Riches on Unsplash)
Pictures provide visual context for your writing. Unlike screenshots
and diagrams, I generally do not create my own pictures.
Fortunately, there are a number of royalty-free, attribution-free,
and other open-licensed image repositories online. My favorite is
Unsplash, but there are many others. My most common use case
f a ic e i a he a icle heade i age f bl g f a e. M
second most frequent use is to break up sections in long, abstract
articles. Avoid using too many general pictures because they do not
directly contribute information to a piece and your readers have
seen similar images hundreds of times in the same context.

83
Diag a f Cha e 8 T ial
Charts, graphs, and other custom diagrams are the most useful
graphics that you can include, but also the most time-intensive to
create. My workflow of choice is Autodesk Sketchbook on the iPad
with the Apple Pencil, but there are dozens of software options for
both handwritten and computer-generated graphics. You can go as
low-tech as a pen, paper, and a smartphone camera. What is
important is finding a tool that works for you and becoming
proficient with it. With charts, you can help visual learners engage
with your work and you can express complex relationships that are
difficult to convey in writing. Diagrams also serve as excellent
introductions or summaries for concepts; they provide readers with
a concrete expression of your ideas.

84
5.3 O e c i gW ie Bl ck
E e e e e ie ce i e bl ck diffe e l . W i e bl ck i
the failure to make effort or progress on a writing task. For me, it
generally occurs when I am working on an article but do not have a
clear next step. Regardless of the stage of the project, it is hard to
sit down to work on something unless I know roughly what I am
supposed to be doing. This issue can stem from one of several
causes.
Sometimes, there is a gap in my knowledge of the subject, a sort of
k k . T l e hi i e, I ead e ce ,
write more test code, explore more real-world systems, or
otherwise step away from the writing process and back into
research. I do not believe in waiting for inspiration, though thinking
about writing does take time. Keep researching and having both
intentional, structured thinking and ad-hoc shower thoughts until
you come to a breakthrough.
One part that is really important to me is that I will read
a complicated thing and something will hit me on an
e i al le el. S e hi g ill hi e he e I like,
ha bea if l ha a a a i g hi g ha he e
fig ed ha a c a ick he did l kh
c l ed a d a ge hi a . I ill ha e a eac i
that is di ec a d i ce al a d if I d ,I ie
about it. The trick is that something intuitively resounded
in me that made me have that reaction and I want to
c ea e e lai ha eac i f eade . If e
trying to explain a complicated thing, e i d, i
complicated. But if you have a strong, clear reaction to
the thing, walking people through your steps to get to that
strong, clear reaction is an easier thing to do because you

85
 feel it, you want to make jokes about it, you want to
express it in a clear way. Matt Levine
Sometimes I know enough to write about the topic, but the topic is
way too big to fit into a reasonable article. This means that I made
mistakes while outlining. The first step is to rigorously narrow the
a icle c e b considering the audience for the article. I remove
both prerequisite knowledge and less valuable tangents based on
explicit assumptions about my target audience. Instead of including
these tangents, I can keep my focus narrow by linking to other
sources at the end of the article to give the reader a more in-depth
look at my subject.
Beyond the scope and my knowledge, sometimes the structure,
outline, or topic of the article does not hold up during the writing
process. Perhaps the lesson turns out to be obvious, the code
trivial, or the article derivative. Again, this is a breakdown in the
outlining and research process, so the best step is to set aside the
article as it stands and revisit research and outlining to find a
unique angle for the article or a better match for the existing
content to a readership.
To write good tutorials you have to be able to put
elf i he h e f e le h eed he . S if i
hel ial , if i f hi g ha a e b ke h
set something up, you have to put yourself there. You
really have to try it from that perspective, even if that
means blocking off some of your existing knowledge and
a achi g hi a if e e he e h e
writing for. Angel Guarisma
I would be remiss to neglect how your working environment affects
your writing. When I am constantly checking social media, dealing
with distractions or interruptions, overly tired, or otherwise not in a

86
good physical or mental place to work, I do not make progress. I
treat writing an article the same as I do writing code; writing
requires the same level of care in constructing an intentional,
effective working environment.
I a id i e bl ck b ched li g i i g i e, ki g
small, achievable sections of my task, and relying on my research,
outline, and sample code. I also have reinvested some of my
earnings from writing in equipment that is a joy to use. I write
almost every day and am flexible in changing my methods to adapt
to my environment and circumstances. I even have dedicated
writing playlists. This is what works for me; use it as a starting point
in figuring out what works for you.

//TODO
1. Write your article. Do not try to write the whole thing in one
sitting. Break down writing sessions according to your outline.
1. Write the introduction to your article
2. Write the first section of your article
3. Write the second section of your article
4. W i e he h ec i f a icle
5. Write the conclusion of your article
2. Find or create graphics that you think your article might need.
If you get stuck, reach out to your editor for help.
3. Do not worry about word choices or the flow of your article
until you have a complete draft. It may be very rough, but
what is important is having something to revise.

87
Chapter 6: Editing
Editing is where the magic happens. I prefer to edit after a break
f i i g, i h a lea a igh lee be ee he la d
written and the first word edited. When editing, you understand
your work in its present state, envision where you want it to be, and
make the necessary changes to get there. Editing is reviewing the
content for intent and execution. In short, it is the entire writing
process again, but rather than starting with a blank page, you are
addressing an existing work as a whole.
What I like about writing is that I can reread it over and
e agai a d d e ii .W ii gi ag d
chance to revise and perfect what you are writing a little
more. When you are a perfectionist in any way or a
procrastinator in any way, that might not necessarily be
the best thing, but that is an advantage because you can
make sure you write something that is the highest quality
you can. Cassidy Williams

6.1 Content
Working through the entire article may seem like a tedious last
step, but it is essential to producing quality content. There is a
perception that grammar and style matter less in tech than other
fields. Enough people share that perception that it is tautologically
true, but that just means that skilled prose makes your writing stand
out from the crowd. Everyone needs differentiating factors, why not
make a strong written style one of yours?
Id edi i g a e he hi g ha I e j i e .
The first editing pass largely focuses on the flow of the
piece. One thing that I do during that is to read the piece
out loud and see if it makes sense at a narrative level. If it

88
 makes sense at a narrative level, great, and if not, I re-
arrange sections, maybe thicken it out, attempt to re-write
the conclusion. My conclusions are always the weakest
part of my pieces. Once I have the piece flowing rather
well, I do another re-read focusing more on a sentence-
to-sentence level. Is the piece a well-crafted artifact in the
E gli h la g age? While I d i g ha I al check f
spelling and punctuation errors. Patrick McKenzie
Run your writing through an automated natural language linter.
The default spellcheck in your word processor or the top plugin
for your text editor should be sufficient. I write words in VSCode,
the same editor I use for code, but still have spellcheck running at
all times. Be wary of false positives, especially in automated
grammar checkers and spellcheck on technical terms. Even with
this automated assistance, careful editing work will reveal flaws in
your writing.
6.1.1 Structural Principles
In your first editing pass, focus on structural issues with the work.
Think at the paragraph level. Ensure that the ideas are presented in
a logical order and that each section connects to the previous
section and sets up the next one. Check that you have covered all
of the important information and be ready to cut anything that does
c ib e he eade de a di g f a icle.
I P fe N a Ra e b kle Learning Technical
Writing Using the Engineering Method, his twelve principles are a
great list of revisions to make during your editing. My thanks again
to Professor Ramsey for allowing me to reproduce this material.

89
1. Correctness. Write correct English, but know that you have
more latitude than your high-school English teachers may
have given you.
2. Consistent names. Refer to each significant character
(algorithm, concept, language) using the same word
everywhere. Give a significant new character a proper name.
3. Singular. To distinguish one-to-one relationships from n-to-m
relationships, refer to each item in the singular, not the plural.
4. Subjects and verbs. Put your important characters in subjects,
and join each subject to a verb that expresses a significant
action.
5. Definitions. Mathematical definitions lack significant actions,
so clarify them using examples.
6. Information flow. In each sentence, move your reader from
familiar information to new information.
7. Emphasis. For material you want to carry weight or be
remembered, use the end of a sentence.
8. Coherence. In a coherent passage, choose subjects that refer
to a consistent set of related concepts.
9. Purpose. Give each paragraph a purpose, which is the effect
you want in the mind of your reader.
10. Paragraph = Issue + Discussion. Begin a paragraph with one
to three sentences, which end by emphasizing the issue. Finish
by using the issue in in coherent subjects or thematic strings.
11. Parallel structure. Order your text so your reader can easily
see how related concepts are different and how they are
similar.
12. Abstract. I a ab ac , d e e a e a li f ic
covered; instead, convey the essential information found in
your paper.

90
6.1.2 Code
Make sure your code samples are complete, runnable, and
readable. Once you think the code samples are finalized and
correct, start from wherever you expect your readers to begin and
actually work through the process of copying and running the code
as the tutorial instructs. Act as the reader and perform the entire
process exactly as described. If you have any issues or bugs, it is
critical that you fix them and update the article accordingly,
otherwise your readers will be disappointed when the tutorial falls
short of its stated goal. In a perfect world, you would be able to test
across platforms on Mac, Linux, and Windows systems, but I have
never done so myself. Be certain to at least test your work in the
environment you created it in.
6.1.3 Reading Aloud
The last step of my writing process is reading my article aloud from
start to finish. I try to write in a natural voice, and if I hit any
wording snags while reading aloud, it is a good sign that the
sentence needs to be refactored. Reading aloud also helps catch
repeated words and phrases, correct grammar issues, and check the
flow and pace of my work. Furthermore, it helps me slow down
and consider the writing; otherwise, I tend to just skim the piece
when reviewing. Before any other person sees what you have
written, read it aloud in its entirety and fix anything and everything
that does not sound right when spoken.
I read aloud or just to myself. My personal writing style is
pretty much as conversational as possible, and I try to
write the way I speak. I want to make sure that it sounds
like I c e i g ith the reader, that it sounds like
e hi g I e ci ed ab e hi g ha he
might find interesting. If it sounds boring the way I write

91
 it or the way I speak it, then that means I need to revise
i . Tha edi i g ce make the writing sound
interesting and conversational. Cassidy Williams
Here are two other ideas for reviewing your work. First, try printing
your article out and read it on paper, colored paper if you have it.
Seeing your writing in a different format will help your editing brain
recognize areas that need polishing. The other is asking someone
else to read your piece. The person does not have to be technical
and does not need to pay attention to the code. Ask a family
member or a roommate to read through what you have written and
respond to any sentence-level issues.

6.2 Style Guides

Established publications may have a house style guide, a standard
style manual, or both. In Subsection 5.1.1, I explained my default
style choices and why I find them generally correct. The
publica i le g ide i he la d a le e i a d
certainly overrules my general suggestions. In your editing process,
e ie he blica i le g ide a d ake e ii g
a che he bli he ecifica i . T i g i clea copy will
speed up the publication process and help the editor
enthusiastically approve your next pitch.
We work with a lot of freelancers. We have somebody
on this team who is exclusively dedicated to interfacing
with freelancers all of the time and editing their work.
We have written a rubric for acceptance, instructions on
how to submit a guide, instructions on how to use Git,
and instructions on all of our tooling so that somebody
can render a document according to our guidelines.
What makes a writer good to work with: someone who
wants to have a long-term freelance relationship with

92
 Linode and somebody who really takes the time to
de a d h e e d i g i a d h e ed i gi.
The e hi g e ha ha i g eb d ig ha
he e ead all f he e d c e a d he ge i g a
piece written in Microsoft Word. Angel Guarisma
A blica i tyle guide is often a far-ranging document. It may
be concerned with titles, tone, citation style, keywords, code
formatting, or any number of other things that an editor has had to
fix enough times to be worth writing down. Do not agonize over or
try to memorize the style guide; instead, make sure that you
understand its intent and fix any deviations in your work that stand
out to you. If you are convinced that a style variation in your piece
is important, be prepared to defend it to the editor.
As you write, it is worth developing your own style guide. Creating
a formalized list of rules that you follow can help you objectively
evaluate your own writing and increase consistency among your
works. For this book, I created a style guide for interview
transcripts that was helpful during the editing and formatting
process. It was important to me to develop a consistent
presentation for all eleven interviews while preserving individual
tone. Once you have a style guide, keep it updated as your writing
evolves and note any special considerations for publications to
which you are a regular contributor.
I g i g a l gi e a e f ha i g high
a da d . A l f e le ell e Y a da d a e
high. M e e i , If a l e a da d ,
j g e he e el e he i e e . Jeff Atwood

93
6.3 Working with Editors
What makes a freelancer good to work with for us is a
willingness to take feedback. We dedicate one writer to a
freelance project who goes line-by-line on something
submitted so that the freelancer can submit a better
submission. The idea is that we create a better long-term
relationship that way, and so even we still get writers
where we ask for revisions and they say no or they ghost
us. Angel Guarisma
Once you have edited your content yourself, it is time to send it to
the editor at the publisher for review. Different editors and
publications have different levels of editorial review. In my
experience, many editors publish what I send them with minimal
copyedits, which is why I put so much emphasis on completing my
own thorough editorial process. However, some editors will
perform multiple rounds of deep and thorough review. There are
benefits to each. An editor with a light touch helps you get to print
and get paid quicker, and may increase your confidence in your
work, while an involved editor will help you to improve as a writer.
The technical editing process is the point in which all of
the writers have the opportunity to, without
consequence, question every decision that was made in
the writing process. If somebody installed something
i g, I d k ,a i ae e i maybe they
added a custom repository or they installed a random
library in that moment the person performing the
technical edit gets to question that a d a k, I hi eall
the right way to do this? Is this really the most helpful
a d hi ? S e i e he e ii g
really care about the stuff that you think is cool, and cool
i ece a il hel f l he a die ce ha c e

94
 this documentation, and so the coolness of it gets
questioned. Then we are able to either accept something
because somebody did make all of the right decision
and then that person can become stronger in their
convictions in their creative decisions (creative used
liberally here because it is technical) or we can catch
mistakes in the process.
Af e ha e ha e a c edi i g ha e, a d c edi i g
ha e i e ac l ha i d like. I l li e
edi i g a d g a a ; i al a ki g if hi i f a i is
presented in the best way possible. We also have this
automated step that happens at the end where we check
for style and spelling and grammar at the continuous
i eg a i le el. We e b il a l f e , hich hel
cap off a piece. After all of tha d e, e ha e a e ie
stage where one person who has not been involved in the
writing of this piece, the editing of this piece, or the
technical review of this piece reads the piece from top to
bottom without actually trying out the steps (that was
done in another stage). They review it and if it meets the
standard of a piece of documentation for us, then we hit
the merge button in the pull request and it goes live at
our release cadence. Angel Guarisma
The most important thing when working with an editor is to be
timely and clear in your communication. Your editor will let you
know exactly what can be improved in your work, and it is your job
to use that feedback to develop both the piece and yourself to the
level that they are requiring. What I send is never perfect, but I
learn from each editor so they never have to tell me to fix the same
thing twice. After the second or third round of edits, the process
can get tedious. Trust that your interests are aligned with your

95
 bli he ; b h f a to put your names on solid work. If
you find you and your editor are bogged down in a seemingly
unimportant back-and-forth, it can be useful to ask them to directly
establish a clear path and criteria for moving on to publication.

6.4 Editing for Self-Publication

Sometimes you want to publish something yourself. However, this
means that you are responsible for outsourcing the editing process
or performing it yourself to assure that your work attains a high
level of quality.
I wrote a self-published book. It li e all a PDF ha I
uploaded to Gumroad and made available online.
The e a li le bi f cha i i , hich lie i ha i
as polished in terms of language, style, and things like
that as a professionally edited book by a top publisher. I
wo ld a hi a ach add al e, b i defi i el
d e ee h . Agai , hi i he e f b k
lea e b k helf. I j a e cha ge f
i f ai ih c e . I a if I did a e-to-
one session with someone I exchange everything I knew
about the topic, but I just do it at scale. Basically, what
I ge i g i ha I d hi k eed e ell
honed skills in writing for this type of book that I made.
Ob i l , I hi k i i a ha e a g d le
tha he e age ge h gh. O he i e e le
like i , he ec e d i , a d he igh lea e
bad reviews or ask for refunds. Daniel Vassallo
6.4.1 Beta Readers
Finding a good beta reader is tricky. Start by returning to your
outline to review your description of your target audience. Then,

96
think of some people, ideally three to five, who match at least some
aspect of that audience and who you think would be willing and
able to provide written feedback.
Your beta readers are not supposed to proofread your piece.
Instead, their role is to approach it as a reader and determine if it
works structurally. Ask your beta readers three questions:
1. Were there any spots where you were confused?
2. Were there any spots where you were bored?
3. After reading the piece, do you have any remaining questions?
Where readers were confused, check for missing steps in your
logic or implicit assumptions that you have made that are not
obvious to readers, and rectify these by adding additional context.
Where they were bored, cut extraneous explanation or provide
better motivation for the content to make readers understand its
importance. Alternatively, it could be a signal that you need to
break up the text with a graphic, list, code block, or other visual
relief from an endless wall of words. If they have questions after the
article, answer them. If the questions are within the scope of the
article, explicitly raise and answer them in the course of the piece.
If the questions are outside of the scope of the article, include them
in the conclusion with links to relevant further reading. Also, those
unanswered questions could be the basis for your next article on
the topic.
Do not feel you must always change your content just because a
beta reader tells you to. Your beta reader might have a background
that is unusual or different from your target audience, and that may
be the source of their boredom or confusion. Exercise discretion in
choosing beta readers and then in applying their advice.

97
6.4.2 Professional Proofreading and Copyediting
Technical editors will do their best to catch grammar and usage
errors, but many are not trained copyeditors or proofreaders. A
proofreader goes through the piece for consistency and correctness
at a sentence level, while a copyeditor also considers the structure
and content of the writing. If you think that a given piece merits the
investment in professional proofreading, make that investment, but
most blog posts will not need that attention. Like any professional
service, you get what you pay for in a freelance editor. For technical
editing, be ready to go toward the top of the market and find
people who will truly help you develop the piece.
In terms of resources, the only thing I used for basic
proofreading was a service called Wordy where a group
of freelance copyeditors do basic grammar and style
corrections. You send them a Word doc and they
annotate suggestions and things that might not be clear. It
babl a ic l ece a . I d hi k ale
or reviews would have ffe ed if I did d hi , b I
think if you can afford it (it cost about $400 in total), it
add a bi e c fide ce ha e e di g
anything out with embarrassing typos or things like that.
Another pair of eyes will reveal things that might not be
clear. Daniel Vassallo
6.4.3 Edits over Time
When you are the publisher, you can change your content at any
time. My personal website explicitly shows an update date for each
piece, and a public Git history should any interested readers wish
to trace changes over time (not that I expect that anyone would).
Even when working with other publishers, you can generally email
updates to your editor if you want to add an endnote or correct an

98
error after publication. While you should edit thoroughly and with
an eye toward correctness and quality, do not place undue strain on
yourself by expecting perfection. I have corrected errors days after
blica i , i cl di g bla a e igh like TODO: add a
e e ce ic X, a d i ha e e bee a e i issue.

//TODO
1. Take the article that you wrote and work through it looking
for structural elements to improve. Analyze your work using
the twelve principles from Subsection 6.1.1.
2. Test all of your sample code in a clean environment,
performing only the steps that your article presents.
3. Read your article aloud to catch sentence-level issues.
4. If you are writing for a publication, check their style guide and
ensure that your work is compliant with their rules.
5. Send the article to your editor and be ready to make changes
based on their feedback.
6. Begin your own style guide. I recommend consulting the most
recent editions of The Chicago Manual of Style and The
Merriam-Webster Dictionary.

99
Chapter 7: Publishing
The fi al e i each a icle c ea i i bli hing. The
publishing process works differently for each publication, or even
each editor. Your editor may give you a style guide or other
document detailing the process, but it may just be an email with
instructions. One thing that you can do to stand out as an author
worth working with is to actually read and follow their process to
the letter. Getting it right the first time does not guarantee getting it
right every time; I maintain and update a document where I write
down the steps of publishing with each of my clients.
For editors who perform lighter edits, I usually send them a
markdown file or a link to a Google Drive folder containing the
document and any associated graphics. They load the article into
their CMS (Content Management System), I approve their version,
and it goes live on a specified date. Editors who want to do a back-
and-forth tend to use collaborative drafting software like Google
Docs and move to the CMS once finalized. I know at least one
publisher that actually uses Google Docs as part of their CMS; the
articles are deployed directly from specifically formatted
documents.
Usually, the editor creates and formats the final article in the CMS,
but some clients have the writer do this step, which takes extra time
but gives you control over exactly how your content appears
visually. Your final task is approving this preview. It should look
exactly how the article will appear on the main site. Whether you
a e addi g he c e elf e ie i g he edi f a i g,
use this as a last chance to proofread before the piece goes live.
Also, check to make sure that your links are working, images are
present where they are supposed to be, and code snippets are

100
formatted correctly. Let your editor know right away if there are
any errors.

7.1 Last Steps

In addition to the article and graphics, various editors will want a
handful of extras. You may be asked for an article summary or pull
quotes to use in the final version. The article summary may be
shared on social media and included under the title. To entice
people to read your article, keep it short, a hundred words or less.
Construct it by pulling out a few sentences from the introduction
that summarize the article.
A pull quote appears out of context in the article as a visual
element to reinforce key ideas. A pull quote is an important
concept from the article that is repeated in larger font to break up a
wall of text. Select interesting pull quotes that are sentence length,
ten to thirty words long, and make sense pulled out of their
immediate context.
You will usually be asked for an author bio and image, which can
be a headshot or avatar. Keep these standardized between
publishers. For your bio, include a sentence about your
background and interests and a sentence about what you currently
are working on. The author bio is a thirty-word advertising slot, but
do not be overly promotional. Keep it third-person, neutral, and
professional. Many publications will also let you link to your
website or social media profiles in or below the bio. This will not
generate much traffic, as a very low percent of readers click
through these links. Nevertheless, the links are always worth
including and occasionally help other publishers find you to
commission articles.

101
7.1.1 Skimmability
Sometimes your publisher will opt to break up your article in the
final version by adding design elements like images, pull quotes,
bulleted lists, and extra headers. This new layout increases the
skimmability of the article. Often, readers will come to an article
from a search looking for a specific snippet of code or information.
Formatting for skimmability is not a sign of any issues with your
article, rather, it is just the editor trying to make the article useful
for a wider audience.
I e bee hi g something for a while I like to call the
skim factor: how well can a reader skim an article?
We e H Ja Sc ch, hich i a l ha ec d
your screen and shows how users navigate through your
eb i e. I f beca e ll ee he clicki g hough
a icle , he e hei ec e , he e he e
ce ai f ha hi g a e. We e f d ha ce he
get to the articles, they would scroll down as fast as they
could until they saw the code block. Then they would
stop, read the code block, and then finally read the
a ag a h ab e he c de bl ck. If he e e
i e e ed, he d kee c lli g il he a a i age,
and then same thing: scroll up above the image to see the
a ag a h. Tha h he aj i f e le e a
read articles.
I a , le b eak he big a ag a h , e i age
in, get code blocks in there, and visually guide a user
h gh a a icle. I hi k ha he e I f
edits for authors. A lot of people write long-form
a ag a h , a d I d hink it leads to the best kind of
experience for readers. Chris on Code

102
7.2 Platforms
There are a wide variety of publishing platforms. The variety is one
f he ea ha each bli he ce i diffe e . A he
author, it should not matter much to you what your publisher is
using, but I think it is still important to get an idea of the
technologies in the space. It will become vitally important if you
want to publish for yourself.
I have no personal affiliation with any of the publication platforms
I am discussing here, and neither, to my knowledge, do my
interview subjects. My recommendations for starting your or your
c a bl g de e d e ce a d eed . If a a
full-featured CMS and are willing to pay a little more for hosting,
go with Ghost. If you have some developer capacity, either your
own expertise or someone who will help you, consider a static site
generator with a custom theme hosted on Netlify. This is what I
use for my own website. There are a number of similar static hosts
that offer speed, security, and customization. If you want most of
those benefits for very little work, use an open-source Jekyll theme
and publish your articles from Markdown using GitHub Pages.
7.2.1 Wordpress
Wordpress is old enough to drive. The PHP-based CMS is the
platform that 35 percent of the internet is built on. It has an
incredibly wide ecosystem of plugins and themes to choose from
and can be customized in countless ways. It features a useful
administrator panel. Basically, it is the default, and for good reason;
it is fully featured and infinitely adaptable.
However, its position as industry standard comes with drawbacks.
Wordpress sites often deal with security issues. The platform has a
large attack surface and is popular, making it an attractive target.

103
Furthermore, I find that many themes show their age, especially in
their responsiveness to different screen sizes. I also dislike how
i e each a icle blica i da e i i he i e i elf, he
URL patterns, and the archives.
If your client is working with Wordpress, it should not be an issue,
but it is not what I recommend for your own site given the
alternatives on the market. If you do decide to use Wordpress, pay
the few extra dollars a month for a host that applies updates and
security patches quickly and reliably.
7.2.2 Ghost
In response to issues with Wordpress, many people have created
their own CMS applications. Dozens of open-source applications,
web frameworks, and Software as a Service offerings are competing
to host your content. I like Django-based CMS Wagtail and Django
CMS because I love the Django web framework, but I do not
necessarily endorse their use. One CMS that I am willing to
endorse, and again I do so without affiliation at the time of writing,
is Ghost. I am not alone in seeing the benefits of this platform:
O ec a ha I e c aged b , al h gh I
ha e ed hei d c a dI a e e b a
means, is Ghost. Ghost is this independent publishing
platform I d k ha e e they embrace that
static site idea in particular, but they are at least with
media companies that are less reliant on advertising and
more using things like subscriptions. Mark
McGranaghan
Ghost is open-source, but the nonprofit organization that develops
it also offers paid hosting plans, a similar model to Wordpress.
One of my regular clients recently switched to Ghost and their new

104
site looks great. I have also worked with the publishing platform as
an author with other clients and wholeheartedly recommend the
experience. The biggest drawback with Ghost is that while sites
made with it look very good, they also all look very similar unless
you invest some time in customization. Nonetheless, between the
their business model and strong technology, Ghost is my CMS of
choice.
7.2.3 Static Site Generator
Whenever possible, I prefer to use a static site generator over a
CMS. A static site generator is a script that runs on your computer,
taking templates and content to output a static site that can then be
uploaded to any static host. A static site is just a collection of
HTML, CSS, and JavaScript that is served identically to all users,
without reference to a database or any functions running on a
server. Static sites are incredibly secure as there is very little to
attack. They are extremely fast as long as you keep page sizes small.
The big disadvantage of static sites is that you cannot collect
information from users or store user data. This shortcoming is no
longer as important as it once was thanks to the proliferation of
both serverless functions and Software as a Service that have made
integrating dynamic components into static sites easy.
Static Site Generators have (re)gained popularity in recent years,
with frontrunners Gatsby, Hugo, Jekyll, and Pelican representing
almost every popular web language. My own website,
https://philipkiely.com, is currently using a custom build script
written in Python, relying on Jinja and Pelican to generate various
parts of the site. I host on Netlify at the moment, but one of the
benefits of static sites is that they can be hosted almost anywhere.
Unless a CMS meets one or more important needs that a static site
generator and Git-based workflow do not, such as support for non-

105
technical writers and editors or minimizing development time, I
would recommend creating your publication with a static site
generator written in your preferred language.
The thing that I dislike about the status quo is that you
go to these sites and they do literally hundreds of HTTP
requests. If you go and open washingtonpost.com this is
one I know because I used it for my slow software
article with your browser tools open and you go to the
networks tab, it will make hundreds of HTTP calls for
one article with a few images. It just feels kind of gross to
e. If l k he e i calli g ,i Faceb k
and Google and DoubleClick. Is this really all necessary
to read an 800- d a icle? Of c e, i l . I
ake he age ji e a d a d efl he i
loading. A lot of the screen is not allocated to the
content. It makes the content hard to archive, and if you
a ca ea a h f he age, i a e . I
also more susceptible to various types of internet
outages. I think there are reasons for why this happens in
the context of the business side.
The model that I like is where you statically generate
something, put it in HTML files, then put it on S3 or
similar, put a CDN in front of it like CloudFront, and
he ha i . A a e d a bill f f d lla a
month, a d he i e e e g e d .I a e e.
Tha ha I e d e i h G b E a le, hich ha
allowed me to basically forget about the site for a year.
Mea hile he e e all ki d f ild hi g ha e i g
out there, like these crazy SSL vulnerabilities and all of
these cloud platforms going down, and I never have to

106
 worry about any of that because it is a simple static site.
F he e , i a e e beca e i e e fa .
There are about three HTTP requests to load a page on
Go by Example, one for the page, one for the CSS, and I
hi k he e e f he li le g he . I e i le.
Tha ha I like he ech ical ide. I hi k ca
get quite far with just hand writing the HTML. On my
personal site, for example, I hand write the HTML and
the CSS. These are in a directory, and I rsync the
di ec S3, e e iall ( he e a c e i ale
f S3), a d he I all e . Wi h G b E a le i a
li le e hi ica ed i ha he e a lchai ha
generates the site. Mark McGranaghan
7.2.4 Ebooks and PDFs
Creating downloadable content requires a different approach. Use
the command-line utility pandoc or any of dozens of other tools to
convert your files into your preferred format for distribution.
Simple ebooks and PDFs are some of the easiest artifacts to create
and distribute, but these are better for books and other more
substantial works rather than articles.
I a i hi g, b ge e a i g he diffe e f a
and styling and things like that was easier than I
expected. I thought it would be a bit more complicated
to get it to work well on the phone or on a laptop. It
turns out that lots of people have done this before, and
there are quite a few resources out there to make it work.
Daniel Vassallo
Adding professional layout and graphic design multiplies the effort
substantially. If your work requires the sort of layout that requires

107
specialized software and skills, seek out appropriate resources and
experts to present your work in its best form.
7.2.5 Print
Outside of full-length technical books, print material is rare but
does exist. Almost all print material is also published digitally.
Printing is substantially more expensive and logistically complicated
than digital publishing. Because of that, print material signals
higher, longer-lasting value. When publishing for print, deadlines
are much more real and coordination is even more important than
with online publications. In your writing, the only things to change
for print are citations (obviously, you cannot do hypertext links
anymore) and how you think about code blocks (they cannot be
copied and pasted; they must be retyped). Beyond that, when
writing for print, keep the longevity of your content in mind when
pitching and outlining, but otherwise write with the same eye
toward quality as for all other mediums. Ultimately, it is the
message, not the medium, that matters.

//TODO
1. If you are working with a publisher, follow their publication
process carefully. Take notes on how they operate so that you
can publish future articles smoothly.
2. If you are publishing yourself, format your work and publish
it. Do not agonize over processes. Get your work in front of
readers first, optimize after.

108
Act 2: The Process in Action
Doth want example: who hath read or heard
Of any kindred action like to this?
King John, William Shakespeare
The best way to improve your craft is intentional practice. The
previous act gave you the tools you need to create professional
pieces of technical content. In this act, we will break them out and
get them muddy. I will walk you through the process of writing two
project-based tutorials and one topic-based article using the
techniques you read about in the previous seven chapters. These
works are the pieces that I have been drawing from as examples
throughout the previous act.
I have been somewhat casual about the distinction between a
technical tutorial and a technical article up until this point, mostly
because the division between the two is nebulous and the process
for creating them is nearly identical. In this act, I will assert a
somewhat firmer definition: a project-based tutorial has sample
code as its main focus; a topic-based article does not, instead
developing a general idea. That distinction does not mean that
topic-based articles cannot include sample code or project-based
tutorials cannot discuss broader themes; it simply refers to the
main goal of the piece.
When I was a sophomore in college, I wrote a simple script for
generating Shakespearean sonnets by remixing lines from
Shake ea e c llec i f 154 e . The c de, i e i e
night with less than a year of study in programming, was hideous.
For example, as I had not yet learned web scraping, I gathered the
data using copy and paste and formatted it using find-and-replace in
my code editor. Nonetheless, the project won the admiration of my

109
English professor, so I left it lurking in a corner of my personal
website. For this act, I dug out the code and used it as inspiration
for two technical tutorials and one technical article. This
demonstrates that even the smallest project can be a seed that
grows into publishable educational content.
I b ke he c ce i h ee a . The fi ial g al i
teach the fundamentals and philosophy of web scraping and data
wrangling with an interesting project; I designed it to be the sort of
tutorial that a reader will commit half an hour to sitting down and
ki g h gh. The ec d ial g al i i d ce a fe
basic JavaScript concepts in the context of the same project. The
hi d a icle g al i i d ce eade e i i g k i he
field of computational poetry.
All three articles require minimal technical skill to follow; they are
beginner-level. While I find the material interesting, I hope the
entry-level nature of the work helps you focus on the details of the
craft over the content. The first tutorial assumes some background
in Python, the second assumes a passing familiarity with JavaScript,
and both require that you already have a general development
environment set up.
Chapter 8 includes an outline, specific notes, and the full text of the
fi ial, Sc a i g a d Ge e a i g Shake ea ea S e .
Cha e 9 i cl de he a e f he ec d ial, P ac ici g
JavaScript with a Shakespea ea S e Ge e a . Cha e 10
ee he a e f he ech ical a icle, C a i al P e .
Writers in any genre will say that in order to write in their genre,
you have to read broadly and deeply. For once, technical content is
not an exception. Deliberately seek out strong examples of
technical content and read with an eye toward craft. You do not
have to exhaustively analyze every technical article that comes

110
across your screen. Simply ensure that you are an engaged reader
of technical content in order to be a successful technical content
author.
Your mission, should you choose to accept it, is to find
authors whose writing is actually good and model your
writing more off of their writing rather than modeling it
off of the writing that is likely to come across your desk
passively. Patrick McKenzie

111
Chapter 8: Example Tutorial: Scraping and
Generating Shakespearean Sonnets
This chapter presents the complete text of the technical tutorial
Sc a i g a d Ge e a i g Shake ea ea S e , al g with an
explanation of my approach to writing and coding for the tutorial.
Thi ial g al f he jec ed a die ce i h a d
explain building a sonnet remixing function from start to finish. As
a side effect of walking readers through building the system, it
imparts specific lessons on web scraping, caching the results of
long-running computations to files, and processing list data. This
article is intended to be read from start to finish while preparing
he a le a lica i i he eade wn development
environment, also teaching the reader the meta-process of
constructing projects.

8.1 Reade N e
For each article in this act, I have prepared some notes for the
reader of this book. While I hope you enjoy and, depending on
your pre-existing technical background, learn from these example
tutorials, that is not my main goal in presenting them here. Instead,
read with a focus toward the craft.
8.1.1 Tutorial Outline
As with the articles I write for clients, I started the writing process
for this article by creating an outline based on my research, which
for this article mostly consisted of dusting off and rewriting the
code from an old project. Here is the outline as I wrote it. Note
that it is a little different in content and structure from the final
article. A flexible writer expects the final article to diverge from the
outline as a result of the writing process.

112
Three major changes in the structure occurred in the process of
writing the article:
1. I moved the discussion of edge cases down from the section
on how sonnets work to the section on parsing the data
because I discovered the edge cases were not important until
that section.
2. Formatting the data after scraping turned out to be completely
trivial, so I wrapped that discussion in with the web scraping
section.
3. The data structure required for a simple sonnet-generation
function turned out to be very non-trivial, so I added an entire
section on that very early on in the writing process.
The outline below is what I wrote before making those changes; I
generally do not update my outlines while writing.
Introduction
System we are building
purpose
outline of stages
Setting Up
Shake ea e k
Who is Shakespeare
Structure of a sonnet
Iambic pentameter
Rhyme scheme
Edge cases in numbered sonnets
Data Collection
Data use: public domain
BeautifulSoup to scrape website

113
 Python sample code: scrape website and load into
memory
Data Formatting
Purpose of data formatting is to get what we collected
into a saved, usable state
write to file for longevity
Python sample code: clean data and write to file
Writing the Algorithm in Python
load data into memory from file in convenient
structure
no arguments, simply generates randomized sonnet
Python code sample: the algorithm
This is exactly the style and level of detail of outlines I write for
myself when working on articles. The main purpose of an outline is
to guide you in your writing; thus, they are not generally for public
consumption. Still, your editor may ask you to send an outline as
part of the pitching process, so it is important to write outlines that
are not completely indecipherable to other people. Furthermore, I
have sometimes come back to outlines weeks after writing them to
actually start the article: writing outlines as a proper documentation
of your thoughts avoids the equivalent of revisiting long-abandoned
code and trying to figure out why it works.
8.1.2 Writing Concepts
After a brief introduction explaining the example project, you are
going to have to ask readers to set up a development environment
to follow along. It is critical that this setup process is as short and
simple as possible and makes very few explicit assumptions about
he c e a e f he e achi e (i.e., e a i g e
installed software like a text editor and web browser). Since the

114
code itself that you created for the tutorial must be architected to
support a simple setup, this should be straightforward. Usually, the
setup steps I give the user are to download or clone a Git
repository, install some packages, and get started. Projects with
more complex stacks (i.e., a webapp with Django) require a few
more steps. Simple projects like this one get away with quick
setups. This tutorial has the reader create three files, pip install
two packages, and move right along.
Y e i g ec i i lici l ide a e e i i e
eade hi : If ca fig e h ge e , his article
ill ake e e. A ch, ha e iea e de ailed
setup guide for beginner-level articles, but if you are writing on
advanced topics do not bore your readers with a step-by-step guide
to opening terminal and launching a virtual environment. Your
editor or style guide may provide guidance on the level of detail
required in this section.
If an article includes a sample project, that sample project will
require domain knowledge to understand. Usually, this is
e hi g like e a e deling a database for a library, and
lib a ie le e le check b k . Whe he d ai
knowledge required is not so common, you need to give readers
the briefest possible introduction that lets them understand the
project. In this article, the rhyme scheme of a sonnet is important
to the project as a whole, so to get readers to pay attention I specify
i he bheadi g ha he E gli h Cla ec i ill be h
(under 200 words) and I provide the explanation in both written
and visual forms.
Break your code samples into reasonable chunks, usually one
function per code block in the tutorial. After each function, explain
the relevant or novel bits of the implementation, not every line. I

115
do break this near the end of the tutorial where I include an entire
file, about twenty lines, but at that point most of the code is similar
to code that has been seen before. Throughout this whole tutorial,
I take care to only put code snippets in the tutorial in the order that
he h ld be c ied i he eade wn files, and I make sure
to specify into which file each segment should be copied.
Code samples should be concise, but not to the point where they
cannot be read. The occasional print statement that you might not
put in your own code can give readers an understanding of what is
going on when the code is running. Statements that could be
combined to save a few lines can stay separated to make the steps
more clearly visible. The idea that code is written once and read
many times is emphasized when writing technical tutorials.
Here is a code sample from the tutorial below:
def get_sonnet(url):
print("getting", url)
req = HTTP.request("GET", ROOT_URL + url)
soup = BeautifulSoup(req.data, "html.parser")
text = soup.find("blockquote").get_text()
text = text.split("\n")
text = [t.strip() for t in text if t != ""]
return text

Here is some code that does exactly the same thing (without the
print) in a one-line function:
def get_sonnet(url):
return [t.strip() for t in
BeautifulSoup(HTTP.request("GET", ROOT_URL +
url).data,
"html.parser").find("blockquote").get_text().split("
\n") if t != ""]

116
This is a somewhat hyperbolic example, but I hope you see the
point: do not play code golf with your readers. Write explicit code
that is easy to read.
Another thing I do for readability is avoid lambda functions. I use a
lot of list comprehensions because I think they are fairly easy to
understand. In my own work, I like map and filter just fine; my
first programming class in college covered solely functional
programming. Still, I cannot assume that readers at the level of this
tutorial are familiar with these concepts, so I use the more
common Pythonic list comprehension, for example:
''.join([c.lower() for c in word if c.isalnum()])

This points to a larger question of scoping articles. Unfortunately,

what to leave in and what to take out is always a decision on a line-
by-line basis. I endeavor to strike a balance by demonstrating good
practices and meaningful optimizations while overlooking nuance
he e i i ce al he ial g al .
An example of pointing out a good practice is reminding readers to
use ast.literal_eval i ead f P h b il -in eval. It takes
a sentence to do and makes a difference in the security and stability
f he eade c de. Re e be , he a e j eadi g he
article to rebuild the system you are demonstrating, they are going
to take the lessons, and often the exact code, and use it to build
their own systems. Set them up for success by taking reasonable
precautions.
Meaningful optimizations also aid your readers. This tutorial
focuses on saving data to files as checkpoints after two different
time intensive (more than one second) processes. Unnecessary
optimizations can confuse your readers, break the pace of your
article, and balloon the scope way past your original intent. For

117
example, bucket_lines is a function in the article that runs in
O(n-squared) time. This could be substantially improved by
rewriting the function to use a disjoint union find algorithm, which
would bring the time complexity down to near linear time, making
the code run several seconds faster. However, this is a non-trivial
implementation worth another article in itself to explain properly.
Thus, the inefficient but simple code stays.
However, it is worth noting when you make key decisions like that
one. I acknowledged the decision in one sentence, not when
explaining the code, but later in the article when I noted that the
code would take a few seconds to run. Explicitly targeting such
notes toward advanced readers (e.g., advanced readers may
ice ) c li e e le h al ead k ab he
algorithm without insulting or confusing people who do not.
In general, acknowledging pedagogical intent is a good strategy for
explaining to readers why you made various implementation
deci i . I he ial, I i e, c a i g URL f a age
and then visiting each of those URLs to scrape those pages is a very
c a e ha I a ed h . A l g a he c de
you are presenting is opinionated, as opposed to wrong, you can
get away with a nonstandard implementation in support of your
ial g al .
Once the code is in the article, it is important to test it for
c ec e . O e f hi b k be a eade caught an error that
only occurred sometimes due to the random sampling that the
article uses. It turns out that one of the hundreds of lists in the final
data set had only one element, which I had not anticipated. It was
caused over 400 years ago by Shakespeare, who rhymed a word
with itself in one sonnet. A simple list comprehension eliminated
the error. This beta reader found the error by writing a quick script

118
to run the final code a thousand times. Similar brute-force testing
can go a long way in valida i g a icle a le c de.
In addition to code blocks, this tutorial contains a few graphics.
There is a key idea in this tutorial called the transitive property of
rhyming. Basically, if a word rhymes with another word, and that
word rhymes with a third word, the first and third words rhyme.
The project necessitates building a complex nested data structure
based on this property. Two graphics do most of the heavy lifting in
explaining these concepts, as diagrams are often substantially more
effective than words in explaining structure and relationships.
Si ila l , a diag a li i g he e c e ide a
alternative to the two paragraphs detailing the poetic form, allowing
the reader to speed through acquiring the necessary domain
knowledge. Finally, two annotated screenshots give readers an idea
of my thought process when I am analyzing a webpage for its
structure before performing a web scrape.
Most tutorials benefit from a short conclusion that restates the key
points of the work. However, most conclusions are boring to write
and boring to read. In this tutorial, I combated that by introducing
a related question: how many different sonnets can the system
generate? As this is a tangent, I could not fully answer this
complicated question; I tried to limit myself to two hundred words.
However, introducing it gives the reader an interesting parting
thought. Adding something like this is not necessary; a lot of the
articles I publish only have a short summary for a conclusion. An
editor concerned about the length of this tutorial might propose
cutting the divergence. However, when you have an interesting
facet of the project that does not fit in the main article, it can be an
effective ending note.

119
8.2 Complete Tutorial

Scraping and Generating Shakespearean Sonnets

A sonnet is a fourteen-line poem in which each line has ten
syllables and the lines connect in a fixed rhyme scheme. Two of
the many hard parts of getting a computer to write a sonnet are that
it is difficult to teach it what a syllable is and it is difficult to teach it
what rhymes. This is especially true in a poetic context where both
of those are loose definitions. What if we could create new poems
while sidestepping these difficulties? Using lines from
Shake ea e nets as building blocks, we are going to create a
system in Python to generate sonnets by remixing lines from across
Shake ea e e . I hi a icle e ill c ea e a e ha
i e f ll e ih he e f a al la g age ce i g
or any advanced text-generation algorithms.
Our first step is scraping the sonnets from a public archive. Then,
we need to format and save the text. We will parse that saved text
to build a data structure of rhyming lines of poetry and save that
data structure. Then, we will use the data to generate sonnets by
selecting rhyming lines at random and printing these lines to the
terminal. This process is accomplished in three stages with the data
saved to a file between stages to cache our work. We want to be
able to parse the scraped data without scraping it every time, and
we want to generate sonnets without recalculating rhyming sets
every time. This article is similarly structured along the three major
stages of this project.
Setting Up
Before we get started, you will want to create a folder for this
project with three files in it: scrape.py, rhymes.py, and poem.py. I

120
recommend working with a virtual environment. If you do so,
create one now for this project. When you are ready, fire up your
Python development environment and we will get to it.
You will need to install BeautifulSoup and urllib3, two libraries that
we will be using to help with web scraping. Run:
pip install bs4 urllib3

All other imported packages are part of the core Python

distribution.
English Class in under 200 Words
Shake ea ea e f ee li e ha e a h e che e a
follows: ABABCDCDEFEFGG. Rhymes alternate lines for the
first twelve lines, or three quatrains, and the poem concludes with a
rhyming couplet. This structure is occasionally broken;
Shakespeare wrote three sonnets that intentionally deviate from
this pattern. After accounting for those, we can use this fixed
structure to deconstruct sonnets for their rhyming lines, and then
construct our own sonnets b a i g Shake ea e h e a e
correct.

121
Sonnet XII Structure
A sonnet is composed exclusively of lines of iambic pentameter,
meaning that each line is ten syllables with a two-part rhythm: an
unstressed syllable and then a stressed syllable. When you are
reading sonnets aloud, add stresses like a heartbeat (ba bum ba
b ba b ba b ba b ). Whe I d c he cl ck ha
ell he i e, ead he fi li e f S e XII, de a i g he
natural cadence of iambic pentameter when read aloud. We
a e ha e e li e i Shake ea e e i i ila l alid
iambic pentameter and thus fit to use in our sonnets.
First Stage: Scraping the Data
We will be getting our data from http://shakespeare.mit.edu/.
Before performing a web scrape, it is essential to ensure that you

122
are doing so responsibly. We will be collecting data from about
150 pages, each of which is about a dozen kilobytes (mostly from
the favicon.ico image). This is a fairly minimal server load. The
da a e a e c llec i g i e i el blic d ai . The i e
robots.txt file has no requests for scrapers. All in all, this looks like
a responsible use of web scraping and we are clear to proceed.
We start out in scrape.py with this boilerplate scraping code:
from bs4 import BeautifulSoup
import urllib3

# Disable warnings, the site is only available over

HTTP
urllib3.disable_warnings(urllib3.exceptions.Insecure
RequestWarning)

# Define global variables

ROOT_URL = "http://shakespeare.mit.edu/Poetry/"
HTTP = urllib3.PoolManager()

The site we are getting our data from has been operating since
1993 and has not been updated much since then. Thus, it is served
over http, not https, so we ask urllib3 to not warn us about
making insecure requests. To save some keystrokes, we define two
global variables for later use.
Web scraping is an iterative exploration. Guided by analysis of a
age c e, e de i e a bi f c de ge a iece f da a, a d
then use that data to get closer to what we want to extract. We
repeat this process until we arrive at our goal. This two-step
example of first gathering links and then getting each sonnet
demonstrates this approach.

123
Start by taking a look at the page that lists all links. Again, this page
was created in the 1990s, so the structure is very simple, making
our scraping task easier.

Sonnet Links
Once we have identified the structural elements of the page, we
construct a function to scrape all of the URLs.

124
def get_urls():
print("getting sonnets.html")
urls = []
req = HTTP.request("GET", ROOT_URL +
"sonnets.html")
soup = BeautifulSoup(req.data, "html.parser")
links = soup.find_all("dt")
for link in links:
urls.append(link.find("a")["href"])
return urls

After initializing an empty list, the function makes a request to the

page, just like a web browser would. The BeautifulSoup object
parses the response data from HTML. Then, it finds all <dt> tags.
For each tag, it extracts the URL (the value for href) from the <a>
tag, which is what creates the link. The function returns this list of
URLs.
You may have noticed the only difference between the URLs is the
Roman Numeral. We could, instead of performing this first scrape,
write a function that transforms the numbers 1 through 154 to their
Roman Numeral counterparts. I did not write the code this way for
two reasons. The first is that this scraping code is so simple that it is
probably easier to write than an integer to Roman Numeral
converter. The second is that scraping URLs from a page and then
visiting each of those URLs to scrape those pages is a very common
pattern that I wanted to show you.
Each URL will lead to a page with the same structure, so we will
write one parsing function and run it on each page.

125
Sonnet Page
This page is even simpler, but we will have to do a bit of text
formatting as well in the following function:
def get_sonnet(url):
print("getting", url)
req = HTTP.request("GET", ROOT_URL + url)
soup = BeautifulSoup(req.data, "html.parser")

126
 text = soup.find("blockquote").get_text()
text = text.split("\n")
text = [t.strip() for t in text if t != ""]
return text

The request and parser initialization are the same as the previous
function. The pages each have only one blockquote tag, so the
function can get the text inside that tag and know that text is the
sonnet. The function returns the sonnet as a list of strings, one for
each line, with excess whitespace stripped.
To run these functions and save a file with the results, add the
following:
if __name__ == "__main__":
sonnets = []
urls = get_urls()
for url in urls:
sonnets.append(get_sonnet(url))
f = open("sonnets.txt", "w")
f.write(str(sonnets))
f.close()

This snippet runs the above functions on the appropriate input,

converts the resultant list of lists into a string, and writes it to a file.
To run this whole process, run:
python scrape.py

The scraping process is usually bottlenecked by bandwidth or

server capacity, not processing speed. To track its progress, this
code prints a line every time it requests a webpage. These
webpages are small, and we are requesting very few of them, so the
whole scrape should only take a few seconds. Still, it is vastly more
efficient to read the sonnets from a file for the rest of this project

127
than to scrape the data every time, which is why the project is
broken into stages. Congratulations, you have finished the first
stage.
Second Stage: Parsing Rhymes
Now that we have the sonnets saved in a local file, it is time to build
a data structure of rhyming lines. First, we need to load the sonnets
from the file we just saved them in and return them to the expected
form of a list of lists, where each sublist has the lines of the sonnets
as string elements. Open rhymes.py and enter:
import itertools
import ast

def load_sonnets():
f = open("sonnets.txt", "r")
source = f.read()
f.close()
return ast.literal_eval(source)

To extract the sonnets as a data structure instead of a string, we use

ast.literal_eval. This function is better than the basic eval
function because ast.literal_eval will only evaluate certain
data types while eval will evaluate anything, even dangerous code
snippets that do things like delete files. Otherwise, this is a
straightforward exercise in reading a file.
Next, we are going to parse the sonnets into a nested list based on
their structure. We do not know if two words rhyme based on
anything other than their position in the poem. We get started
breaking up sonnets with the following function in rhymes.py:
def parse_couplets(sonnets):
couplets = []

128
 for s in range(len(sonnets)):
sonnet = sonnets[s]
if s == 27: # nonstandard last line length,
drop that couplet from dataset
couplets.append([sonnet[0], sonnet[2]])
couplets.append([sonnet[1], sonnet[3]])
couplets.append([sonnet[4], sonnet[6]])
couplets.append([sonnet[5], sonnet[7]])
couplets.append([sonnet[8], sonnet[10]])
couplets.append([sonnet[9], sonnet[11]])
elif s == 98: # ababacdcdefefgg rhyme
scheme in this poem
couplets.append([sonnet[0], sonnet[2],
sonnet[4]])
couplets.append([sonnet[1], sonnet[3]])
couplets.append([sonnet[5], sonnet[7]])
couplets.append([sonnet[6], sonnet[8]])
couplets.append([sonnet[9], sonnet[11]])
couplets.append([sonnet[10],
sonnet[12]])
couplets.append([sonnet[13],
sonnet[14]])
elif s == 125: # aabbccddeeff rhyme scheme
in this poem
couplets.append([sonnet[0], sonnet[1]])
couplets.append([sonnet[2], sonnet[3]])
couplets.append([sonnet[4], sonnet[5]])
couplets.append([sonnet[6], sonnet[7]])
couplets.append([sonnet[8], sonnet[9]])
couplets.append([sonnet[10],
sonnet[11]])
else: # ababcdcdefefgg rhyme scheme standard
among other sonnets
couplets.append([sonnet[0], sonnet[2]])

129
 couplets.append([sonnet[1], sonnet[3]])
couplets.append([sonnet[4], sonnet[6]])
couplets.append([sonnet[5], sonnet[7]])
couplets.append([sonnet[8], sonnet[10]])
couplets.append([sonnet[9], sonnet[11]])
couplets.append([sonnet[12],
sonnet[13]])
return couplets

This is a lot of lines of code, but it is a very simple function. The

issue is that Shakespeare, being an artist, occasionally broke the
rules in sonnet construction. To account for these special cases, we
use an if-else statement to provide special parsing logic for sonnets
with different lengths and rhyme schemes.
Now, we have a list of lists in which each sublist contains at least
two strings that rhyme with each other. However, we want to be
able to create valid rhymes between lines from different poems.
Thus, we establish the transitive property of rhyming.
The transitive property of rhyming works as follows. Two lines in a
sonnet that rhyme form a couplet. Given two couplets, couplet X
and couplet Y, if a line in couplet X and a line in couplet Y end in
the same word, the second line in couplet X must rhyme with the
second line in couplet Y. We can extend this property to sets of
lines of arbitrary size: if even one line in a set X has the same end
word as one line in a set Y, every line in set X rhymes with every
line in set Y.

130
Transitive Property of Rhyming
By parsing lines into sets according to this property, we will
c c la ge e f h i g li e ba ed lel Shake ea e
presentation of what it means for words to rhyme. The large
be f e , a ell a Shake ea e ela i el li i ed et of
end words, makes this a feasible approach. Here it is in code for
rhymes.py:
def last_word(line):
word = line.split(" ")[-1]
return ''.join([c for c in word if c.isalnum()])

def shares_last_word(list_a, list_b):

a_last_words = [last_word(l) for l in list_a]
b_last_words = [last_word(l) for l in list_b]

131
 return any(w in a_last_words for w in
b_last_words)

These two helper functions perform critical operations. The

function last_word extracts the last word from a line in a sonnet
by breaking up the string into a list of words, split at the space, then
selecting the last word. It returns the word in lowercase with all
c ai i ed e e ha da a che Da ! The
function shares_last_word takes two lists and extracts lists of last
words from each of them, then returns True if any of those last
words match or False if they do not. It does so using the any
function, which takes a list and returns True if at least one of the
elements of that list is truthy, or False if not. In rhymes.py, add:
def bucket_lines(lines_list):
for i in range(len(lines_list)):
for j in range(len(lines_list)):
if shares_last_word(lines_list[i],
lines_list[j]) and i != j:
lines_list[i] = lines_list[i] +
lines_list[j]
lines_list[j] = []
return [e for e in lines_list if e != []]

The main event is a double iteration over the same list. For each
element in the list, compare it to every other discrete element of
the list (so it skips comparing itself to itself). If elements share a last
word, combine them and empty one of them. If they do not share
a last word, move on. The function empties one list rather than
deleting it to preserve the indexes that the iterator relies on. If one
or both lists passed into shares_last_words is empty, the
function will return False, the value that any([]) evaluates to.
After the iteration, the function returns a list of all non-empty lists.
These lists are transitively rhyming sets of maximum size on the

132
input. In our example, we go from over 1,000 couplets to about
300 lists, dramatically increasing the range of our rhymes.
There is one final step to perform on the data. When writing a
poem, having two lines that rhyme because they end in the same
word is pretty boring. To combat this, we will complicate our data
structure by adding another level of sub-lists that group rhyming
lines together. This is getting convoluted to explain in text, but the
data structure we are going for looks like this.

Rhymes Data Structure

Fortunately, we do not have to write a grouping function ourselves.
Instead, we will use itertools.groupby from the Python
standard library. This function requires each sublist to be sorted,

133
but fortunately we can do that using the last_word function from
earlier. Add in rhymes.py:
def sublists(rhyme_lists):
new_buckets = []
for lst in rhyme_lists:
new_lst = []
lst.sort(key=last_word)
for key, group in itertools.groupby(lst,
last_word):
new_lst.append(list(group))
new_buckets.append(new_lst)
return [b for b in new_buckets if len(b) >= 2]

Thanks to itertools, this function is fairly concise. For each list

in our list, we create sublists that have one or more elements where
each element is a line of a sonnet that ends in the same word. We
return our newly re-bucketed lines, ensuring that each bucket
contains at least two sublists (this catches one edge case).
Finally, we put this all together in rhymes.py to run the file:
if __name__ == "__main__":
sonnets = load_sonnets()
couplets = parse_couplets(sonnets)
buckets = bucket_lines(couplets)
rhymes = sublists(buckets)
f = open("rhymes.txt", "w")
f.write(str(rhymes))
f.close()

Run the following in your terminal or shell:

python rhymes.py

134
It might take your computer a few seconds to parse the sonnets (as
tested: 7 8 seconds on an Intel i9-9900HK, MacBook Pro 16").
Advanced readers may note that the bucket_lines function
running in O(n^2) time is responsible for much of this slowdown
and that the process could be optimized with a disjoint union find
algorithm. However, that implementation is outside the scope of
this article. In any case, we still want to write the results to a file: it is
faster to load the text source of this size than to run bucket_lines
every time we want to generate a sonnet.
Now the hard work is behind us and it is time to make poems!
Third Stage: Building Sonnets
With the work from the previous two stages completed, actually
generating sonnets is a very straightforward process. We can
consider the code as a whole in poem.py:
import ast
import random

def load_source():
f = open("rhymes.txt", "r")
source = f.read()
f.close()
return ast.literal_eval(source)

def write_sonnet(source):
couplets = []
rhymes = random.sample(source, 7)
for rhyme in rhymes:
r = random.sample(rhyme, 2)
couplets.append([random.choice(r[0]),
random.choice(r[1])])
sonnet = ""

135
 for i in range(0, 5, 2):
sonnet += couplets[i][0] + "\n"
sonnet += couplets[i+1][0] + "\n"
sonnet += couplets[i][1] + "\n"
sonnet += couplets[i+1][1] + "\n"
sonnet += couplets[6][0] + "\n"
sonnet += couplets[6][1]
while not sonnet[-1].isalnum():
sonnet = sonnet[:-1]
sonnet += ".\n"
return sonnet

if __name__ == "__main__":
source = load_source()
print(write_sonnet(source))

The load_source() function is nearly identical to the previous

one, again using ast.literal_eval() to safely load the data.
Our write_sonnet() function first builds seven rhyming couplets,
and then orders those lines into a sonnet. First, it samples seven
rhyming sets without replacement, meaning that none of the seven
couplets should directly rhyme with each other. Then, from each
set of sets of rhyming lines, it samples two sets, which have one or
more lines in them that end in the same word. It takes two sets
without replacement to avoid rhyming a word with itself. From
each set, it chooses one line at random, constructing the couplet.
Next, the function takes the seven couplets and arranges their
c e i a e h i g a e . Thi i acc li hed i h
a for loop over a range by steps of two, which saves several lines.
The final couplet has both its lines added at the end. The last step
is stripping away any punctuation from the end of the sonnet (using
a while loop as there may be more than one character of

136
punctuation). The function then punctuates the last line with a
period and returns the sonnet.
Thanks to the work we did in the previous two stages, this simple
random selector can generate a valid sonnet every time.
To generate a sonnet, run:
python poem.py

Here is a sonnet that the system generated for me:

Or at your hand the account of hours to crave,
With lines and wrinkles; when his youthful morn
That god forbid that made me first your slave,
With Time's injurious hand crush'd and o'er-worn;
And given grace a double majesty.
And their gross painting might be better used
Thy registers and thee I both defy,
Where cheeks need blood; in thee it is abused.
My most full flame should afterwards burn clearer.
Thy edge should blunter be than appetite,
Even those that said I could not love you dearer:
For if it see the rudest or gentlest sight,
O, therefore, love, be of thyself so wary
Bearing thy heart, which I will keep so chary.

In Conclusion
One interesting question somewhat outside the scope of this article
is how many valid sonnets we can generate from our dataset. This
tricky piece of combinatorics unravels as follows. Starting out, it is
not so bad: given seven couplets, how many ways can you make a
sonnet? Well, seven couplets fit into seven slots in 5,040 different
ways, (7!/(7 - 7)!), but then we have to account for each
couplet being able to fit into the slot in one of two line orders,

137
adding a term of 2^7 orders, and 7!*(2^7) equals 645,120. Okay,
that is a big number, but we are just getting started. We choose
seven rhyming sets from three hundred six such sets at the start of
the sonnet generation, and (306!/(7!(306 – 7)!)) is
46,515,922,124,400. This is before accounting for the number of
couplets that each rhyming set can generate. Then, we would have
to multiply all of these numbers together. Do not worry if you are
having trouble wrapping your head around these numbers, your
CPU would as well.
All of this math reveals that despite the relatively small input size to
the sonnet generator, you can reasonably expect it to never
generate the same sonnet twice as long as its random selection
function is truly random. You can also rest easy knowing the
infinitesimal likelihood of generating a sonnet that Shakespeare
actually wrote. Given the number of sonnets it can create, I have a
feeling that if Shakespeare had access to a tool like this, he would
have been quite a bit more prolific than he already was.
To get a system capable of generating so many sonnets, we
programmed in a three-step process. First, we responsibly scraped
a blic da a e ga he all 154 f Shake ea e e . The ,
we processed the lines into a nested list by the transitive property of
rhyming. Finally, we constructed sonnets by random sample. This
process demonstrated the importance of caching the results of
long-running processes like a web scrape and the iterative
exploration of both scraping and parsing data.

138
Chapter 9: Example Tutorial: Practicing
JavaScript with a Shakespearean Sonnet
Generator
This chapter presents the complete text of the technical tutorial
P ac ici g Ja aSc i i h a Shake ea ea S e Ge e a ,
along with an explanation of the specific tactics I used. This tutorial
has a different goal than the previous one; it seeks to use a project
as a backdrop to present some beginner-level JavaScript concepts.
This different goal manifests in numerous facets of the tutorial,
from the setup to the conclusion. Also, this tutorial is much
shorter, just 1,000 words including sample code. The tutorial does
re-use one image and a bit of content from the previous one, so it
would have to be published by the same publisher in its current
form to avoid copyright concerns.

9.1 Reade N e
This tutorial picks up where the last one ended. You could expand
into other tutorials from the code in this tutorial; at least one of
similar scope on just the HTML at a very beginner level. These
ial c ld be bli hed de a e ie like Begi i g
Ja aSc i Fi C e i Web De el e . Addi g i le
features generates a whole series. (e.g., you want to send someone
webpage with the sonnet exactly as it was generated, or you want to
show a real sonnet and a generated one side-by-side and have users
guess which is which.) If you have a publisher who wants to publish
them, it is okay to extract as many tutorials as you can from the
same project.

139
9.1.1 Tutorial Outline
Again, I wrote an outline. This short outline does match up to the
final tutorial. I started with topic goals rather than trying to explain
the entire project. Also, the outline reflects the shorter length and
beginner level of the tutorial, especially in the intro and setup
sections.
Introduction
50 100 words on what we are building
list tutorial concepts/goals
Setting up
Provide overview for getting the sample code and
setting up the dev environment
Show working site
How to navigate nested array
How to include and use _.sample()
How to build a string, insert into DOM (note, do not use or
define term DOM)
How to link a function to a button
Conclusion
Ideas for further development using just these four
skills
Notes on areas outside scope of tutorial
9.1.2 Writing Concepts
Tutorials for beginners must be especially generous to the reader.
These tutorials strike a difficult balance between giving
straightforward explanations of concepts that feel very basic and
trusting that even though the reader is a beginner, they are smart
and motivated to follow your content. You need to hold their hand

140
and support their learning without slowing them down. You need
to move past some concepts and content without seeming like you
are withholding information. This tutorial does some of that, but it
i de ig ed be e e fi e e Ja aSc i . Thi
ial i de ig ed be eadable i hi e e s first month of
web development; writing for their first day is a different challenge
entirely.
Because this tutorial is structured around topics rather than a
project, it is able to list all four learning goals in the introduction.
Presenting them as a list rather than some sort of thesis sentence
d a he eade a e i he i f ai ha he ca
check if this tutorial contains information that they need.
The setup section for this tutorial has the reader download a
prepared repository rather than working from scratch. Because this
project relies on the large rhymes data structure, copy and paste
would be infeasible for giving the reader all of the code they need.
Furthermore, some parts of the HTML page are not presented
within the tutorial, this way the reader never has to see that code
unless they want to. The setup section includes an image of the
final webpage so readers can visually verify that they have the
project up and running. Another option for a simple setup would
be to include all of the code in an embedded CodePen or JSFiddle
online playground.
Unlike the previous tutorial, code samples are not presented in the
order that they appear in the file. Some code samples are even
repeated, or a shorter excerpt is shown while presenting a specific
point. This is possible because the reader starts the tutorial with the
complete code on their computer rather than building it alongside
the guide. It allows the tutorial to discuss code snippets in blocks
that are shorter than a single function, which is critical because this

141
tutorial spends its full 1,000 words discussing a single twenty-line
JavaScript function.
The c cl i , like he e i ial , e a d he
concepts in the main body before restating them. This time, the
conclusion invites the reader to attempt some modifications to the
system using the techniques they have learned over the course of
the article. It is important to make these suggestions specific and
achievable using the tools from the tutorial but not completely
i ial. The ce f aki g e e el e c de a d al e i g i
slightly so it does what the reader wants is an incredibly important
fi e f a e le lea i g ce , a d a begi e le el
tutorial has the opportunity to present this learning skill alongside
technical content.

142
9.2 Complete Tutorial

Practicing JavaScript with a Shakespearean Sonnet

Generator
Writing any poem is difficult, and writing a sonnet is especially
hard. This fourteen-line poetic form requires that each line be ten
syllables of iambic pentameter and rhyme in a specific pattern:
ABABCDCDEFEFGG. We are going to skip the hard work of
writing sonnets by hand, instead using JavaScript to generate
sonnets from a prepared data structure of rhyming lines from all
154 of Shake ea e fa e .
This article will cover the following important concepts for new
JavaScript developers:
1. Working with nested data structures using loops and indexing
2. Making random selections using the underscore.js library
3. Building strings and inserting them into a webpage
4. Triggering a function using a button
Setting Up
Download or clone the source code from this GitHub repository.
Open the files index.html and poem.js in your text editor, and also
open index.html with a web browser. You should see the following
webpage appear on your browser:

143
Sonnet Generator Webpage
Click the red button to generate a sonnet, and click it again to
generate a new one. Refresh the page to clear the sonnet.
Now that you can generate the sonnet, we will explore how the
program works.
Data Structure: Arrays in Arrays in Arrays
In a previous tutorial, Scraping and Generating Shakespearean
Sonnets, I go in-depth on scraping and parsing Shake ea e
sonnets to create a dataset of rhyming lines. Fortunately, that hard
work is done, so we can focus on parsing the results. The file

144
rhymes.js contains a single array, called rhymes. Visually, rhymes
has the following structure.

Rhymes Data Structure

Within the array, there are about three hundred subarrays, which
we will call child-arrays. Each of these child-arrays is made up of
more arrays (grandchild-arrays), which each contain one or more
strings. Strings within grandchild-arrays all end in the same word,
strings within child-arrays rhyme with each other. We want to
construct our poem by selecting seven random pairs where the
strings are from the same child-array but different grandchild-
arrays, so they rhyme but do not end in the same word.
Despite how complex this data structure might first appear,
working with it is actually very easy. Here is the code from poem.js:

145
var couplets = [];
var samples = _.sample(rhymes, 7);
samples.forEach(rhyme => {
var r = _.sample(rhyme, 2);
couplets.push([_.sample(r[0]), _.sample(r[1])]);
});

First, we declare a new array, couplets, that is going to store our

seven couplets. Then, we choose seven child-arrays from our
rhymes data structure to choose lines from. We use a forEach
loop, which does exactly what it sounds like: the same operation
for each of the seven child-arrays. We pick two different
grandchild-arrays, and then pick a random line from each of those
grandchild-arrays. Using push, we add those lines to the couplets
array.
One quick note: r[0] is selecting the first index of the r array
constructed by selecting two grandchild-arrays from the active
rhyme child-array. Arrays are zero-indexed, meaning that you use
r[0] to get the first element and r[1] to get the second element,
as we did in our example. r only has two elements, so r[2] would
cause an error.
Making Random Samples
The above code uses a popular, powerful library called
underscore.js to make a random sample. We are able to use
underscore.js because of an import in the HTML in index.html:
<script
src="https://cdnjs.cloudflare.com/ajax/libs/undersco
re.js/1.9.1/underscore-min.js" integrity="sha256-
G7A4JrJjJlFqP0yamznwPjAApIKPkadeHfyIwiaa9e0="
crossorigin="anonymous"></script>

146
<script src="rhymes.js"></script>
<script src="poem.js"></script>

The library is served by a CDN. The order that these scripts are
included on the page is important. poem.js is only able to use the
underscore library from underscore.js and the rhymes data
structure from rhymes.js because it is located below them on the
page.
Regarding the random sample function itself, take a look at how it
is used:
var samples = _.sample(rhymes, 7);

The _ is the underscore.js object that provides the functions. The

sample function takes two arguments: an array and an integer,
which is the number of things to select from the array. This is a
sample, so it selects without replacement, it cannot select the same
element from the array twice. The function returns a new array
with the selected elements. For more on underscore.js, check out
the documentation.
Building and Adding a String to the HTML
Now, it is time to actually build our sonnet. We have seven
h i gc le , hich be de ed i he e
ABABCDCDEFEFGG rhyme scheme. Consider the following
from poem.js:
sonnet = "";
for (var i = 0; i < 5; i += 2) {
sonnet += couplets[i][0] + "\n";
sonnet += couplets[i + 1][0] + "\n";
sonnet += couplets[i][1] + "\n";
sonnet += couplets[i + 1][1] + "\n";

147
}
sonnet += couplets[6][0] + "\n";
sonnet += couplets[6][1] + "\n";

The sonnet begins its life as an empty string. We define a for

loop, and within it an index variable i that increments by two for
three iterations. Remember array indexing? We can use it multiple
times to get the index of child arrays in our couplets data
structure that we built above. We iteratively add lines to the sonnet
with the += syntax and make sure to append a newline character
(\n) at the end of each line. After the three ABAB sections, we
finish the sonnet with a final rhyming couplet as the form requires.
Inserting the sonnet on the page only takes a single line of
JavaScript:
document.getElementById("sonnet").innerText =
sonnet;

This line sets the text of the element <p id="sonnet"></p> in

our index.html to equal the sonnet. It does so by finding the
paragraph in the HTML using its id, or a unique identifier we
ecified i he HTML ag, a d he e i g he ele e e b
e i g he ag innerText attribute.
Making a Sonnet on a Button Press
In the final webpage, you can generate the sonnet by pressing a
button. To achieve this, we first wrap all of the JavaScript code we
have seen so far in a function. The whole function looks like this in
poem.js:
function writeSonnet () {
var couplets = [];
var samples = _.sample(rhymes, 7);

148
 samples.forEach(rhyme => {
var r = _.sample(rhyme, 2);
couplets.push([_.sample(r[0]),
_.sample(r[1])]);
});
sonnet = "";
for (var i = 0; i < 5; i += 2) {
sonnet += couplets[i][0] + "\n";
sonnet += couplets[i + 1][0] + "\n";
sonnet += couplets[i][1] + "\n";
sonnet += couplets[i + 1][1] + "\n";
}
sonnet += couplets[6][0] + "\n";
sonnet += couplets[6][1] + "\n";
document.getElementById("sonnet").innerText =
sonnet;
}

Then, we can call that function from the button in index.html:

<button onclick="writeSonnet();" class="text-center
btn btn-danger">Write a Sonnet</button>

The onclick attribute takes a JavaScript function call as a string

and executes that function when the button is clicked.
In Conclusion
JavaScript is a very capable language, and today we covered how to
do four things with it: navigate nested arrays, take random samples,
construct strings and put them in the HTML, and trigger functions
on a button press. Try using these skills to extend the sample
project. Can you make two sonnets appear? Can pressing a button
add another sonnet rather than replacing the existing one? Peruse
the included sample code to take a look at how the page is

149
constructed. Experimentation is a great way to practice these new
skills.

150
Chapter 10: Example Article: Computational
Poetry
This chapter presents the complete text of the technical article
C a i al P e , al g i h a e la a i f ecific
tactics used. As a technical article, this differs from the previous
two examples as it does not contain sample code or endeavor to
teach the reader how to create a specific artifact. Instead, this article
introduces readers to thinking about a class of problem, in this case
computational poetry. However, it is still informed by our previous
k i h Shake ea e e , e e ie ce hich gi e he ice
in this work more validity.

10.1 Reade N e
Unlike the previous two tutorials, this article does not contain any
sample code or require you to run anything on your machine. A
technical article like this can be enjoyed on the train to work or
during a lunch break. As you read, think about the differences
between a technical tutorial and a technical article, their respective
goals, and how each is useful as part of the massive repository of
educational content that your work enters.
10.1.1 Article Outline
This outline was written during and after the research process.
First, I gathered my sources. I prefer to include at least three
research papers and at least three real-world examples. This outline
focuses on synthesizing and organizing my research, giving readers
a structured introduction to the topic. Unlike tutorials, where
structuring the content is as easy as following the implementation
order of the project, the outlining for a topic-based article like this
takes some creativity. Ultimately, I structured this article around

151
methods of generating poems, where the methods increase in
technical complexity and theoretical sophistication as the article
progresses.
Introduction (300 words)
Can computers make art?
Is meaning inherent in text or projected by the reader?
Bot or Not
T PhD d eed f hi a icle: E gli h a d
Machine Learning
Three of text generation: naive selection, Markov
chain, GPT-2 (example of neural networks) for writing
poems
Why Poetry (200 words)
Generating text is hard because of parts of speech
Generating some kinds of poetry is even harder
because of rhythm, rhyme, and structure
Because of the many different types of poetry and
ways of interpreting them, it may be simpler to create
passable poems than prose
An Algorithm is only as good as its input (200 words)
Quantity, quality of input data
more advanced method require more data, like a
racecar requires high-end fuel
Naive Selection (200 words + example poem)
Shakespeare example
minimum coherent unit / line level of abstraction,
enormous number of outputs
Examples & analysis (example + 100 words)
Markov Chain (200 words + example poem)
How does a Markov chain work

152
 examples and analysis (example + 100 words)
Neural Networks (200 words + example poem)
GPT-2: training and overview
GPT-2 not released into the wild
Examples and analysis (example + 100 words)
In Conclusion (200 words)
Can computers write poems? Maybe. Does this mean
the end of poets? No.
Other applications of text generation
Further Reading
All links from research step
I am in no way binding myself to these estimated word counts.
They are incredibly rough and in my writing I frequently overshoot
or undershoot by half. However, these word counts are a way to
remind myself of the scope of each section and to ensure that the
pieces combined, at their minimum likely lengths, constitute a
whole article. I know I cannot write a complete introduction to
neural networks and apply the concepts to poetry in 200 words, but
targeting that scope focuses my writing and helps me avoid biting
off more than I can chew for an article.
10.1.2 Writing Concepts
Thi ech ical a icle e dea f he he eade k ledge
about programming, either through presenting them with new
algorithms or new applications, without a single line of code. The
value that this article delivers is not new information, but new
understanding. I have saved readers time by presenting my
research in an organized and approachable manner. In the first
three paragraphs, I explicitly communicate these goals along with
background information about the topic. With a technical article

153
you need to be just as explicit as with a tutorial in describing the
scope of the work so that readers can make an informed decision
as to whether they want to read the piece.
Ca c e ge e a e e i a c lla he e i i
meaning inheren i a , i i jec ed a , hich i
i d ce deba e be ee a eade i e e a i a d he
a h i e . A I i e hi a icle, I d i e df i e e
into this proud and longstanding debate, but rather to acknowledge
it on the way to surveying the field. It is important to let readers
know that these questions exist and that they are outside the scope
of the article.
After providing a bit of background on some technical challenges
in text generation and finding sufficient input data, I move into
explaining three approaches to make poetry. For each approach, I
give a couple of sentences of intuition as to how the algorithms
work, but I outsource the technical details to specific sources
written by people with more expertise on these topics. This keeps
me at a reasonable word count and delivers my readers to hand-
picked sources I have verified for correctness and comprehension.
Including examples of poems generated from a single corpus
under each of the three algorithmic approaches gives my discussion
of their relative strengths and weaknesses a concrete basis. Without
these examples, I would be communicating entirely in abstract
terms. Instead, they fill the same role as sample code in a tutorial
and give me platforms to build bridges between. For each, I keep
my analysis brief, letting readers draw their own insights from the
generated poetry.
Including a further reading section acts as a miniature bibliography
for works I cited throughout the text and presents readers with
options to investigate further into areas of the topic that interest

154
them. In the conclusion, I encourage readers to follow compelling
links and learn more about computational poetry.

155
10.2 Complete Article

Computational Poetry

Macbeth: First Folio (Matt Riches on Unsplash)

Can computers make art? We know that people use computers as
tools to create art, with varying levels of interference from the
machine itself. Sometimes the computer simply renders the work,
be it text or a VR cityscape, but sometimes it has a more generative
role, procedurally creating a world to explore or using a Markov
chain to generate text. Algorithms can generate texts that, at
minimum, have passed as poetry and been published, like this
example. How is this possible? Biting off a small piece of this
question, we will investigate how programmers have sought to teach
computers to generate, or even write, poetry.

156
I would love to discuss the potential literary implications of
computational poetry with some real epistemological rigor, but
unfortunately questions about whether text is inherently meaningful
or readers project meaning onto it will have to wait for some other
time. I invite you to consider how the works we will discuss affect
your understanding of the nature of poetry. One place to start this
investigation is examining poems on Bot or Not, a website that lets
you guess whether or not a poem was written by a person.
However, this article focuses on surveying the technical approaches
available today.
There are two PhDs that you do not need to read this article: one
in English poetry and one in machine learning. Computational
poetry can use cutting-edge text generation algorithms, but you can
generate poems with for loops. It raises questions about the nature
of written work, but does not need to answer them. My goal in this
article is to give you an admittedly incomplete overview of methods
for generating poetry and enable you to begin your investigation
into the aspects of the field that interest you. Specifically, we will
cover three methods of text generation for poetry: naive selection,
Markov chains, and neural networks.
Why Poetry?
Generating meaningful text is difficult, to say the least. Not only do
you need to choose the right words, but you also have to put them
in the right order! All forms of text generation deal with natural
language issues involving parts of speech and tend to struggle with
content coherence. Some poetic forms complicate this even further
by requiring that lines be a fixed number of syllables, poems
contain a fixed number of lines, repetition occur at various
intervals, and lines rhyme in defined schemes. These constraints

157
can guide the generator, but they can also make it difficult to create
original and meaningful works.
However, poetry does offer one advantage: it is a very loosely
defined genre. Many people have pushed the limits of what
constitutes a poem; readers do not necessarily expect poems to be
structurally or grammatically coherent, at least at first glance. Thus,
some forms of contemporary free-form poetry give leeway to the
idiosyncrasies of generated text, such as non-standard punctuation,
allowing computer-generated poems to masquerade as human-
written.
Considering Inputs
Just like human authors need to read widely to understand and
enter a genre, so too do computers. Text generation algorithms are
generally not domain specific. The same approaches apply to
writing poetry as to emulating news articles, song lyrics, movie
dialogue, or any other type of text. To make poetry, you take the
same system and train it on a corpus of poems. The text generation
algorithm uses tokens, be they words, phrases, or lines, from the
original texts and recombines them to create poetry.
The better your input, the better your output, regardless of the
alg i h . He e, be e i ea ed a e: a i a d
quality. The quantity of data that text generation algorithms need is
surprisingly high. Systems run on anywhere from hundreds to
hundreds of thousands of poems. If a text generation algorithm is
given too small a training set, it is unable to come up with original
connections, instead regurgitating the same limited sets of phrases
on which it was trained. Considering quality, data needs to be
cleaned (free of metadata like author names and line numbers),
formatted consistently, and parsable to the algorithm. Like a race
car without fuel, the most sophisticated text generation algorithms

158
will sputter to a halt without massive amounts of high-quality input
data.
Naive Selection
The simplest form of poem generation is incredibly
straightforward: grab tokens from a dataset and keep on appending
until you have reached the desired length. If the tokens are
individual words, this will almost certainly result in a garbled mess.
However, with larger tokens and a few constraints, this method can
generate correct, if not necessarily original, poems in highly
structured forms.
Sonnets combine many of the strictest aspects of poetry: fixed
rhythm (iambic pentameter), structured rhyme scheme
(ABABCDCDEFEFGG for Shakespearean sonnets), and limited
length (fourteen lines). In the tutorial Scraping and Generating
Shakespearean Sonnets, I walk readers through the process of
creating a Shakespearean sonnet generator. Based on a dataset of
154 sonnets, the generator randomly selects rhyming lines and
builds a poem of exactly fourteen lines with the correct rhyme
scheme. However, these poems are not particularly original as they
e e Shake ea e k a li e a a i e, h gh f e e l
combining lines across poems. Still, the system is able to generate
effectively endless unique combinations from a relatively small
dataset. Here is an example:
Even those that said I could not love you dearer:
Presents thy shadow to my sightless view,
My most full flame should afterwards burn clearer.
My most true mind thus makes mine eye untrue.
Neither in inward worth nor outward fair,
And guilded honour shamefully misplaced,
One blushing shame, another white despair;

159
And right perfection wrongfully disgraced,
Attending on his golden pilgrimage;
But then my friend's heart let my poor heart bail;
But makes antiquity for aye his page,
Thou canst not then use rigor in my gaol:
I found, or thought I found, you did exceed
Till I return, of posting is no need.

Naive selection can work in other forms but will always face a big
tradeoff between incoherence and unoriginality. This is a valid
Shakespearean sonnet but does not include anything beyond what
Shakespeare wrote. These next two approaches sacrifice a bit of
coherence but gain much more in originality.
Markov Chains
A Markov chain is an algorithm that switches between different
states. I like to visualize Markov chains as graphs, where each state
is a node and weighted edges represent transition probabilities.
However, Markov chains are frequently implemented as transition
matrices. Here is a great visual example of Markov chains in action.
Applied to text generation, Markov chains use words or phrases as
states and weight transition probabilities between them based on
their position in the original text. With enough input, this can give
the algorithm a lot of options from each word, multiplying the
number of possible poems. This approach gives the algorithm
some chance of achieving grammatical accuracy, as each word
should be followed by an appropriate part of speech. Finally, the
algorithm may incorporate some random factor to guard against
getting stuck cycling through the same path.
Here is an example that uses Markov chains to generate poems:
Ma ie Cha field Markomposition. Using the same set of 154

160
Shakespearian sonnets as an input, the algorithm generated the
following output when asked for a sonnet with a medium level of
fusion (that is, a medium token size and overlap).
but those tears are pearl which thy glass will show
thee how thy beauties wear, Thy dial how thy
worth a limit past my praise, And therefore
have I not free. Whoever hath her wish,
thou hast done: Roses have thorns, and silver
fountains mud; Clouds and eclipses stain both
moon and sun, And loathsome canker lives in
sweetest bud. All men make faults, and even
I in this, Give them thy fingers, me thy
lips to kiss. The expense of spirit in

While this is not a classic sonnet by definition nor as complete as

the one generated by the previous system, it is certainly more
inventive in combining phrases; the individual lines are now
original. In my opinion, the first four lines do not make much
sense, but the poem picks up steam midway through line five with
R e ha e h ha la h gh h li ki . Wi h a bi
more structure and punctuation, this system could have a good
chance of generating something entirely believable as a poem from
hi i e . All e ake fa l , e he e , a d fa
the same is true of machines, at least when writing poetry.
Neural Networks
Another method of text generation with a graph-based visual
explanation is neural networks. A neural network is a group of
nodes that represent neurons and process information. One
example of a neural network system for text generation is GPT-2.
Made by OpenAI researchers, the full model with 1.5 billion
parameters was deemed too powerful to release publicly out of

161
fears that it might be misused. Still, a version of the model with a
tenth as many parameters is an extremely sophisticated text
generation algorithm. Machine learning engineer Adam King built
Talk to Transformer with this public algorithm, and it can generate
poetry by filling in its guess for the rest of a sonnet, prompted with
four lines.
This example could only take a short input, so I gave it four very
famous lines from Sonnet XVIII:
Shall I compare thee to a summer's day?
Thou art more lovely and more temperate:
Rough winds do shake the darling buds of May,
And summer's lease hath all too short a date:

and the algorithm completed the poem with the following:

But thy solemn and majestic bridegroom with laughter
bright,
The stars to heaven added do crown and adorn:
All that summer hath I, and all that summer shall I
Like him, happier henceforth to live.
Poor sod, I do know that thy heart can get nothing
With him, to get a morsel, though what part
The rock shivers with the angry sea's moaning.
But here an old dame of the town has a husband
Who lives by her own means, and paid

As the output progressed, it grew less and less Shakespearian,

h gh he i e e i d i fl e ce i fel h gh he e .
Again, this is not quite a sonnet; it overshoots by one line, does not
rhyme, and certainly does not stick to iambic pentameter. This is
not surprising; GPT-2 was trained to generate text, not write
sonnets, and this is unconstrained output. Moving away from the
sonnet form, we can nevertheless consider this poetry. Lines like

162
 The ck hi e i h he a g ea a i g a e i e l ical.
Importantly, this is the first method we have observed to truly go
be d Shake ea e d a da e igi al c ii
from a more complete dictionary of the English language.
In Conclusion
These are not the only methods available to programmers to write
poetry generators. Algorithms focused on parts of speech, rhyming
with natural language processing, and other supervised and
unsupervised learning approaches all can generate interesting
works given sufficient input. Ultimately, regardless of your level of
technical sophistication, you can remix words or phrases to
generate compelling poetry. Can computers write poetry? Maybe,
with the right algorithm, input, and definition of i i g. Will hi
put poets out of business? No.
Text generation, as applied beyond poetry, uses all three of the
methods we discussed and more for tasks like writing basic news
stories (given formatted stock market data, make an end-of-day
trading report), writing essays (often with humorously incorrect
results), or creating pop songs (which face many of the same
structural limitations and allowances as poetry). As the creators of
GPT-2 warn, this is a powerful ability that can be used maliciously,
for example to generate vast quantities of highly targeted fake news
stories. However, text generation can also be a fantastic, practical
application of a wide variety of algorithms toward worthy goals.
Further Reading
Bot or Not
My Poetry Generator Passed the Turing Test
Generating Topical Poetry
Tutorial: Generating Shakespearean Sonnets (See Chapter 8)

163
Markov Chains: Text Explanation
Markov Chains: Visual Explanation
Generating Poetry using Neural Networks
GPT-2 Announcement
GPT-2 Paper
Talk to Transformer

164
Act 3: The Business of Writing
If the matter of this paper be certain, you have
mighty business in hand.
King Lear, William Shakespeare
Writing can be a fulfilling hobby, but it can also be a great source
of income. I made thousands of dollars in my first year freelance
writing, and I only write on a very part-time basis due to work and
school. Any competent writer can do the same by producing
valuable work for businesses that need it. I will not pretend that the
hourly rate for writing about software rivals the hourly rate for
i i g f a e, b i ca ill f a lid addi i a e
income. Beyond direct compensation, writing offers intangible
benefits like an expanded professional network, a sense of
satisfaction from teaching others, and a chance to shape and extend
industry-wide conversations on the topics you care about most.
This act focuses on unlocking all of these opportunities.
I think a lot of the people that I talk to start by producing
content. The patterns that I see are people produce
content with kind of the same aims that I had with Indie
Hacke . I all he e d i a d f i elf i a
means to an end. Courtland Allen
Understanding the business of writing will make your content
better and your publication cycle faster. You will get different kinds
of editorial feedback, different writing assignments, or different
guidelines from clie clie . O ce de a d clie
business models and how your work fits into them, these seemingly
arbitrary differences will make sense. If you know what your editor
is looking for and why they want it, you can avoid rewriting by
doing it their way the first time. Once each piece meets the

165
 bli he eed , ha e i e ice, a d he
sooner your work meet those needs, the more time you have to
make each piece your own best work.
To use a gross approximation, business is a technical
system for convincing people to do things that are in
their interests. As technologists, we should be extremely
interested in technical systems that convince people to
do things that are in their interests. There are more
instrumental reasons to care about how business thinks
ab hi g : i e e el ele a ca ee g al
and career planning; it will result in you getting more
material benefits out of your career; and it will make it
easier to get projects done in your company because
there will typically be business decisions makers who will
be in the critical path for getting stuff done, particularly
as you get more advanced in your career. The
fundamental insight of why business is important to
technologists is that it is a technology like any other one.
It is amenable to the skillsets that you already have and
will make you more effective at the other technical
skillsets that you have. If you approach it with the right
i d e , i ac all e hi g ha i e e el f .
That is my elevator pitch for it. Patrick McKenzie
Computing professionals have a unique advantage in selling our
writing. Most markets, from personal essays to literary short fiction
to young adult novels, have an oversupply that makes it difficult to
get noticed, much less published. While there is a large amount of
technical content online, in my experience the demand for high
quality articles on software engineering topics meets or exceeds the
supply. As we are bolstered by this strong demand, I believe that
we have a responsibility to make money ethically and not

166
compromise our personal editorial standards. Understanding the
business of writing will help you avoid situations where your name
is the byline on a piece you are not proud of on a website you do
not believe in.
In Chapter 11, we will consider how to price your work
appropriately given the market. Chapter 12 discusses contracts and
invoicing, followed by Chapter 13 on intellectual property and
publication rights. In Chapter 14, we will compare the four ways
that publishers of all sizes are able to turn engaging articles into
money. Chapter 15 outlines numerous methods for promoting
your work and engaging with the developer community online. In
conclusion, Chapter 16 opens up the discussion to review long-
term opportunities that may present themselves once you have
established your presence in the field.
As a general disclaimer, which will be repeated where specifically
applicable, this act does not offer legal, tax, investment, or similar
advice. It is shaped by my own limited perspective and may be
inapplicable outside of the specific context from which it is written.
You should consider the contents of this act, especially in the
chapters on contracts and intellectual property, an informative
starting point to further research the legal implications of your
writing. I have endeavored to offer a broad overview of the field
that should help you understand your best first steps to take in
joining the ranks of online writers.

167
Chapter 11: Pricing
People do not comfortably talk about how much money we make,
but we should. This chapter is designed to help you understand
how much you ought to be getting paid for technical writing. There
are four methods of pricing articles, one of which you should use
(flat rate per article, priced on scope) and three of which you
should not use (per word, per hour, or free, for various reasons).
For a specific and up-to-date look at what people are getting paid to
write, visit a website I maintain at whopaystechnicalwriters.com.
I have made as little as 85 and as much as 500 dollars for writing an
article. My most successful article by views netted me 150 dollars,
my longest article was purchased for 200 dollars, and the article
that was the quickest to research and write yielded 400 dollars.
Anecdotally, there has been little correlation between article length,
lines of code, topic, publisher size, or any other easily identifiable
factor and the amount of money that I have made for writing an
article.
One of the first things I ever saw was TouchPlus. They
were advertising that they paid $250 for an article and
that was pretty intriguing to me. I actually attribute that to
e f he e he e I h gh , I a
ech ical i i g. The , I ac all e a a icle. I
published it to Scotch and never went to TouchPlus, but
I think advertising the number helps. Chris on Code
There are two ways to think about pricing: pricing by cost and
pricing by value. Generally, the only cost of writing an article is
your time, for which you may have a fixed per-hour price. I urge
you to ignore that approach and focus on the value that your work
can provide. If you can provide enough value that a company is

168
willing to pay what you consider a fair price, then great, write for
them. If not, negotiate in good faith or pursue another client.
There are more than enough publishers willing to pay a fair price
for good technical writing.
Generally, the publisher sets rates and you, the author, have the
option to negotiate. Good publishers either list their rates publicly
or quote them in response to accepted pitches. As the author, you
have the opportunity to challenge the price, but I have found that
publishers are generally more willing to negotiate on the scope of
the work rather than the price. One solid tactic for increasing a
price is to split the proposal into multiple articles, each of which is
paid at the full rate. However, you will need to ensure that your
topic is substantial enough to merit the split, and that each portion
serves as a valuable stand-alone piece.
Sometimes, publishers have built-in rate increases after your first
article. Smashing Magazine publicizes rates of 200 dollars for the
first article and 250 dollars for subsequent articles. Twilio quotes
an equivalent 50-dollar increase after your first article for them.
Some publishers offer even larger rate increases to reliable regular
writers. Do not reduce your rates because you are new to writing in
general or trying to get your foot in the door. Any publisher that
accepts a pitch has done so because they want to pay their full
regular rate for content at their usual quality standards.
S e i e , e aile ffe ce ai d c a l leade d i g
big sales. A loss leader is a product offered at a price so low that
the retailer takes a loss on each sale, which they make up for with
the profit margin on products that customers buy alongside the loss
leader. I think about writing in a similar vein. If you are used to the
hourly wage for software engineers, article income will seem quite
low, as on average freelance software engineering creates more

169
business value than freelance technical content development. But,
while articles are often a time investment of five to ten hours, good
luck finding software engineering where you can complete a green-
field technical work product in that amount of time. Furthermore,
when you consider that you are getting paid to learn and improving
your public profile, as well as getting direct feedback on your work
from an experienced editor, it can make financial sense to spend
some time writing. For me, a college student, writing has not just
been for spending money; I have been able to invest in my
equipment and education thanks to earnings from my writing.
I have worked for companies across the world, including two
headquartered in Germany and one in Canada. In every case, all
pricing discussions have been in US dollars. Similarly, this book
assumes pricing in US dollars, as article payments offered by
publishers should not vary based on where writers live.

11.1 Per Article

Per article pricing is the most common; all but one of my clients
explicitly price per article. All of my clients and I share a general
sense of what constitutes an article: a rough word count, developed
example project or research, and all of the less tangible aspects of a
complete work like stylistic polish and good pacing. I am done with
an article when it matches the pitch or an agreed-upon
modification thereof, often after one or more rounds of revisions.
Given the fixed, narrow scope of an article, it is one field where
per-project pricing makes the most sense.
Experienced freelance programmers frequently warn against per-
job fixed pricing, and for good reason. Pricing a software
development project at a flat rate, a , 10,000 d lla f a eb
a , e i e a igh c e a d g e i a i g abili ie f i
be a good experience for both sides of the table. Frequently, new

170
features and requests can creep into these large projects, as can
unexpected difficulties and delays, swallowing a once promising
profit and threatening the completion of the project itself. The key
differentiator between software development projects and articles is
the scale. I have never spent more than twenty focused hours
completing an article, and most take half that or less.
At Scotch, since we started as a smaller blog, we
advertised $50 100 for a news-type article and up to
$300 350 for technical articles. Chris on Code
As for how much you should charge per article, as I said above, it
varies, but not based on the properties of the article itself. At this
point, I do not write for less than 200 dollars per article, and I
generally earn between 250 and 400 dollars per submission. There
is no difference in effort between writing an article at a 400-dollar
price point versus a 200-dollar price point; the challenge is in
identifying publishers that value work with those higher rates.

11.2 Per Word

At face value, this seems like it should be the fairest method of
pricing. Longer, more in-depth articles take more time to research
and write and provide more value. However, here is a
philosophical question: if you can write at the same level for 1,500
or 2,000 words and deliver the same information, which article is
better? I would argue that a shorter article is better as long as it
does not sacrifice readability and style for brevity. When you are
writing with per-word pricing, you have to individually justify the
existence of every word in the piece, if not to the editor, then to
yourself.
F he e, he defi i i fa d i ech ical i i g ca be
pretty tricky. A dozen lines of code may be a very sophisticated

171
algorithm in a concise language, taking hours to develop and test
but only counting for a handful of words. Time spent creating
images and graphics, linking sources, and tightening prose is
important work but contributes negligibly to the word count.
The one time I discussed a price-per-word job with an editor, we
ended up agreeing on a fixed price for the finished article before I
started writing it. Unless you have a compelling reason for doing so,
I recommend against accepting price-per-word assignments. If you
do end up pricing per word, estimate the final word count and
divide your per-article price by that figure to get your per-word rate,
and make sure to build in some padding for sample code, graphics,
and other work that does not directly increase the article length.

11.3 Per Hour

The unit of work (an article) is small enough that most of the
benefits of charging for hourly work are void. The scope is fixed,
delivery quick, and editorial feedback resolved in one or two
rounds. I have never asked for or been offered an hourly contract
for article work.
In any project, determining what counts as billable time is difficult,
but for writing it is especially hard. I do plenty of research for my
articles, much of it fruitless or tangential. Furthermore, I find that I
write away from the keyboard, turning over key ideas for hours or
sometimes even days before sitting down and putting the structure
on paper. I have no effective method of fairly quantifying the
amount of work I do for an article as an hourly sum, and I thus
would not write at an hourly rate if I was asked to. I enjoy the
freedom of my writing process too much to price per hour.
You should still estimate the amount you are making per hour for
your own planning purposes. Even tracking for yourself, it is tricky

172
to determine what counts as an hour of work, but this can be a
rough guess. Having this data can tell you how much you make per
hour with writing as compared with other work, which can help you
determine how much time to devote to writing projects.
An exception I make is for editorial or related work. If my unit of
output is not a publishable article, the normal freelancing rules of
engagement are back on the table and time-based pricing may be
appropriate. If a writing project is big enough that it is too risky to
bill at a flat rate, then it is big enough to bill in some better
increment like daily, weekly, or per smaller deliverable.

11.4 Free
I ill a i e e ha bee a e e f ea . E e
serious professional operating in a creative field has to turn down
ig e lici a i d k i e cha ge f bei g aid i
e e. I he i d ci hi cha e , I e ab t the
benefits associated with technical article writing that somewhat
justify the lower average hourly earnings compared to freelance
software development. Why not do it solely for those benefits?
Considering the plethora of reputable publishers offering to pay for
your work and grant the same benefits, I strongly discourage writing
for free for other businesses. If you create something of value, you
should be rewarded for it. Furthermore, if a company is paying you
to write an article, it is more likely to invest editorial and
promotional resources in your work.
Generally, my advice to most people is to make as little
as possible free. Where the line usually gets drawn is
e le ake hi g f ee he he e i e di g g
their audience, and they make hi g aid he he e
intending to make money. Some things are easier to

173
 grow, others are easier to use to make money.
Courtland Allen
The exception here is guest posting. In a guest post, you provide a
free article to reach a new audience. This is more common outside
of strictly technical tutorials, falling more under the realm of
opinion and personal blogs. If you are writing for exposure, you
should have some method of monetizing that attention, such as a
linked publication of your own, a paid information product, or
your consulting practice. In this type of guest post, you are
effectively doing content marketing for yourself, so you need
something of value to market.
People are writing on dev.to, people did it, or still do it
on Medium, and they do it for free there. Writing for
sure makes you understand a topic better than if you had
just done a project, because to teach something in article
form, in person, or in video, you have to know ten times
e ha ha e i g each, e eciall a
conferences where questions are going to come at you
fi e ec d af e ed e ih alk . I hi k
people like the community building aspect of it. Our
authors have used their writings on Scotch to
demonstrate their writing portfolios, and I honestly think
that technical articles are an excellent part of a portfolio
if e i g g ge hi ed e he e. Chris on
Code
I publish for free frequently, but on my own blog. These shorter,
more personal posts are not the type of content that could have
become an article with any of my clients, so I am not undermining
my own business. I do not need to conform to any editorial
standards but my own, and I retain complete ownership and

174
control over my work. I applaud everyone who publishes free
content in the interest of fostering community and supporting their
field, and I encourage every writer to do so. However, be certain to
not confuse providing readers with free content with providing a
business with a valuable asset that they could easily pay for.

//TODO
1. Track your time and expenses while writing. Your first article
may cost more to write than subsequent articles both because
you are exploring your workflow and because you may
purchase software or equipment.
2. Go to whopaystechnicalwriters.com to get a sense of the rates
that different publishers offer. Established writers are invited
to contribute to the site.
3. Consider the rates that your publisher pays. Does the pay
seem fair? If not, look for a new publisher for your next work.

175
Chapter 12: Contracts and Invoicing
When you write an article for a client, you are doing business-to-
business sales of an informal sort. You are in the business of
providing a product, technical articles, which other businesses are
interested in purchasing. However, due to the relatively small scale
of most writing engagements, certain formalities are often
overlooked during the process. For some clients, I have not signed
a formal contract, although I prefer to do so. Whether contract or
letter of agreement, there should be a written agreement in place
between you and your client regarding the scope of the work,
expected payment, intellectual property rights, submission
requirements, timeline, and other such clauses.
If you are in a conversation with a prospective employer,
c g a la i , e d i g e e i e ale , he he
you know it or not. Patrick McKenzie
I am not a lawyer, and this is not legal advice. Neither my own
words nor interview excerpts should be treated as legal advice, here
or elsewhere in the book. This entire chapter is based on
observations and opinions formed through my own experience and
research and may not apply to you and your situation. Every
publication operated differently.
Contracts do not exist in a vacuum. It is important to carefully
consider how your potential freelance activities interact with other
contracts you may have signed, especially employment contracts.
Untangling this issue, along with other issues that vary from person
to person such as the formation of a business to absorb writing
income, fall outside the scope of this book. As neither a lawyer nor
any other sort of registered advisor, I can only recommend that you

176
do your own due diligence prior to engaging in business activities.
Trust your gut, and consult professionals as needed.

12.1 Common Clauses in Contracts

You may need to sign a contract and, less often, tax papers or other
forms of employment paperwork. It should go without saying that
you should review these documents carefully. Assuming you are
provided a contract, it should be short and straightforward. One
publicly available contract that is representative of the sorts of
c ac ha I ha e ig ed i Digi al Ocea Freelance Writers
Contract. (A he i e f i i g, I ha e bli hed i h Digi al
Ocean.) The twelve-section contract offers its own plain-language
interpretation of each section, but I will highlight some important
pieces.
Ge e all , a c ac i cl de a Te , a e i d f i ef
which the clauses are in effect. This term is usually indefinite,
though both parties have the ability to cancel the contract. There is
usually a section that specifies that itself and some other sections
will survive the termination of the contract. Contracts are often
general, an umbrella under which you will develop your ongoing
status as a contributor to a given publication.
Similarly, the contract will likely include some conditions specifying
that you have agreed to the contract of your own free will and are
legally able to enter into the contract. An important concept in
these sections is the idea that the client is not going to get in trouble
because they signed this contract with you. Much of the language in
the contract exists to assign and mutually limit liability. Language
regarding your status as a freelance writer falls into this category.
The contract should specify, in general terms, the services that you
are going to provide to the client. When I say general terms, I

177
 ea e hi g al g he li e f The a h ill ide
igi al a icle he bli he . The ecific f ha alifie a
an article is left to the discretion of you and your editor. A section
on payment should specify that you will be paid the agreed-upon
amounts for the agreed-upon work, in the agreed-upon timeframe,
but may not specify exact figures, as the contract you are working
with may be fairly generic. When writing articles, the payment may
be specified in a separate document or email.
There should be a clause or two about ownership and credit for
your work. We will discuss this more fully in Chapter 13, but for
now make sure that the language is sufficiently narrow to apply only
to the work that you intend to perform for the client and does not
give them any claim to work that you do outside of the scope of
your article-writing agreement.
While a full-time employment contract may contain non-compete
language of varying levels of strictness, your contract with a
publisher should not contain any exclusivity or non-compete
clauses, assuming you are writing articles on a freelance basis.
While the publisher may have exclusive rights to the exact article
you write for them, they should make no restriction to your ability
to write for competing publications or on similar topics. I have only
once had a publisher ask for any kind of non-competition clause,
and I had it removed from the contract before agreeing to write for
them. Stand up for yourself and protect your business; do not sign
non-competition agreements when publishing articles. There are
plenty of reputable publishers who do not ask for these unfair and
restrictive terms, so if you cannot get the publisher to budge, take
your work to other publishers. Note that book publishers and
other purveyors of larger work may ask for some topic exclusivity
for a fixed period of time, which I consider more acceptable given
the magnitude of investment from both parties in the work.

178
Most companies include confidential information clauses. If you
sign a contract, it will probably contain language informing you that,
should you be party to any company secrets, you should not share
them. As a writer, this could mean keeping your mouth shut about
products you are documenting before launch, upcoming API
changes you are writing a tutorial for, or even just editorial
practices. Overall, people tend to take confidentiality seriously.
One of the reasons that I am a writer is because I prefer a more
open world where information is shared widely, but I still carefully
honor confidentiality agreements. Given that freelance writers are
usually not handed top-secret files to work with, you should usually
be able to freely discuss your work, especially after it has been
published.

12.2 Writing Your Own Letters of Agreement

Every contract is a negotiation, and if you are asked to provide the
contract (or, more informally, a letter of agreement), you are
negotiating from a place of strength. When I have written my own
letters of agreement, it has been for smaller clients who want to get
something in writing but mostly care about proceeding to the actual
work. Generally, these letters of agreement can be short and to the
point, with fewer clauses than contracts provided by a lawyer. It is
important to assume the other party is negotiating in good faith
and, given the relatively low value of a single article, it is unlikely
that you would find it profitable to seek restitution for breach of
contract. Thus, focus on writing your contract with simple, clear
language.
My letters of agreement specify services to be rendered, payment
quantity and terms, and intellectual property rights to be assigned.
In the services to be rendered section, I describe in general terms
what kind of writing I will be performing, for example, a ech ical

179
a icle i h a le c de a d igi al g a hic . F a e e ,
I generally specify payment upon acceptance of the article, invoiced
through the payment processor of my choice, currently Stripe. For
intellectual property, I consider my i i g k f hi e, b I
retain the right to be credited as the author. These are not
necessarily the terms that you will want to use, but they are an
example of how I think about letters of agreement. While I
sometimes work without a contract, having at minimum an
informal letter of agreement ensures that you and your client are
entering into the engagement with compatible expectations.
There are a number of open-licensed contract templates that you
can use or adapt to suit your writing activity. Should you decide to
use one, be sure to review it carefully and edit it where necessary so
that you are not inadvertently agreeing to terms that you do not
de a d a e i clie a d be i e e .

12.3 Invoicing
While the actual process can be a bit tedious, invoicing should feel
like a success! You have done the work, and it is time to collect the
reward.
Generally, I invoice the editor with whom I have been working.
The editor then passes my approved invoice on to the accounting
department. For some repeat clients, I invoice the department
directly. The invoice process varies by customer but is generally
pretty straightforward, usually involving an email and an attached
PDF i ice e a ed ba ed he clie e la e. If I a
instead asked to prepare my own invoice, it is usually because I am
working with a client with flexible billing practices. Then I issue
them an invoice directly from Stripe rather than working through
he clie fi ed e .

180
12.3.1 Payment Processors
There are dozens of services available. For security and
convenience, use as few as possible, and transfer your balances to a
real bank account as soon as possible. Rates are pretty similar
across the board, with most services charging a base rate of 2.9
percent plus 30 cents flat per transaction, generally assessed to the
receiver of funds. Unless your contract explicitly specifies that the
publisher will pay associated fees (which is unusual), expect the
a e ce fee be ded c ed f e a . If you
and the publisher are in different countries, expect higher fees, up
to five percent of the transaction cost. This is a cost of doing
business.
If you can use Stripe, I recommend that you do so. Their pricing is
fair and transparent, their customer service is excellent, and I
believe in the company and its vision. Several people interviewed
for this book are associated with Stripe, I use Stripe and Stripe
A la f b i e ,a dI ld like S i e I c e e
magazine to one day be a client of mine, but none of these factors
or any other external factor are swaying my recommendation of
their services.
PayPal is still the industry default for payment. In my experience, if
a publisher specifies up-front that they pay via PayPal, the service is
so ingrained in their workflow that it is not worth trying to get them
to use a different one for you unless you are unable to use PayPal
for some reason.
Quickbooks, FreshBooks, Wave, and dozens of other accounting-
related software vendors all offer billing services. In my experience,
their offerings are roughly comparable in core features and fees.
Your bank may even offer invoicing. Wire transfers are also an
option, but are less common in my experience due to the relatively

181
small amounts involved in article-related transactions. I try to stay
away from all of these options, not due to any specific shortcoming
of any particular service, but in the interest of maintaining as simple
a payment infrastructure as possible.
I have used TransferWise in the past for international payments.
Their fees are somewhat lower than other platforms for
international transfers but their user experience, which attempts to
act as a bank rather than a payment processor, is more complex
than the processors that we have discussed thus far.
12.3.2 Payment Terms
In business, net-D payment means that payment is to be delivered
at most D calendar days after services are rendered. Net-30 is the
most common term. Your contract may not specify payment with
such exactness, but you should expect payment more quickly than
that, often within a few days of the article being accepted after
publication. Generally, the amounts for an article are small
potatoes to the payer and require only one or two people to touch
the transaction, so you should be paid relatively quickly.
Submitting your invoice after the acceptance of the article but
before its publication is standard. When the editor has indicated
that your article is ready for publication, it is appropriate to inquire
as to how they would like you to invoice them. Standard practices
around polite but firm follow-ups apply when payment is slow to
come. Your work is valuable, and you deserve to be paid for it
promptly. As you build your client base, be certain to keep a good
record of outstanding invoices, payments, and processing fees.

//TODO
1. Review any contracts you have received from publishers to
make sure you understand and agree with the terms.

182
2. Remember to invoice your editors after the acceptance of
each article.
3. As your business grows, contact appropriate legal and tax
professionals for your business needs. Keep excellent records.

183
Chapter 13: Intellectual Property and Publication
Rights
As a writer, you create intellectual property that you sell to
publishers. It is important to understand what you are selling. Slight
variations in wording in your contract with a publisher can alter the
structure of intellectual property assignment, substantially changing
the value proposition of the deal to both you and your publisher.
In general, the more rights you give up, the more you should be
paid. Selling anthology rights or second serial rights to a work will
net less income than selling first serial rights, which in turn are
worth less than work for hire, which is worth less than work for hire
without attribution. The publisher should know exactly which
rights they intend to buy, but it is up to you to evaluate if the
payment offered is worth your while.
Here again is my disclaimer: I am not a lawyer and none of this is
legal advice. This chapter is intended as a study guide, not a
textbook.

13.1 Publication Rights

Tech publishing, outside of books, somewhat re-invented the
wheel on rights, built on a foundation of work for hire, like other
freelancing projects tend to be. While I will provide a full
discussion of different types of traditional publication rights, you
will probably only encounter work for hire and modified versions
of first serial rights when publishing articles.
Depending on the publisher and the work, you are selling or
licensing different rights. Some publishers want an exclusive
monopoly on using your work, others only care about certain
mediums, regions, or periods of time. Some allow re-publication of

184
articles after some time has passed, provided that you use a
canonical link to the original and disclose where it was first
published. Very rarely, a publication will agree to republish
something that has been published elsewhere, usually for a much
lower fee.
Regardless of what kind of rights you assign to a publisher, if you
later want to use the work in a way that violates those rights, you
can always ask the publisher for permission in writing to do so.
They may say no, but it does not hurt to ask.
13.1.1 Work for Hire
Work for hire, the most common treatment of intellectual property
by article publishers, is the idea that you, the author, create
intellectual property (an article) which you then sell to the
publisher, who then owns the intellectual property as if they created
it themselves. This is the same treatment of work product that
applies in most software engineering jobs, where code you write
becomes the property of your employer.
Personally, I think this is a very fair way to assign intellectual
property for articles. When I write an article for a client, I am
writing it for that client. I would not have much use for it myself.
While much of the relatively high price per article in technical
content comes from the technical skill required to create the
content, some definitely compensates for signing away all rights to
the work.
Work for hire is almost universal with corporate blogs and other
content marketing operations. If you are performing freelance
editing, documentation, internal writing, copy writing, creating
marketing emails, or any other sort of general writing-based
contract work for a company, it will almost certainly be contracted

185
as work for hire. Some magazines and other advertisement-,
sponsorship-, or subscription-based businesses ask for work for
hire.
13.1.2 First Serial
First serial rights are a very common request in traditional
publishing. The publisher purchases the right to be the first to
bli h a gi e k. Thi e i e e f bli hed k
includes any public-facing site, no matter how small. You cannot
publish the material on your blog or anywhere else ahead of
publication or during a prescribed period. After a period as the
exclusive publisher of the work, the publisher releases rights back
to you, letting you sell second serial or anthology rights to the work
(first serial rights, by definition, cannot be sold twice). While first
serial rights are generally worldwide, they can vary region by region.
While a version of first serial rights are fairly common in technical
content, they are often not explicitly called first serial rights, and the
rights work slightly differently. Generally, the article is still
considered work for hire, but after a period of time, sometimes as
little as a week or two, you are allowed to republish it to your own
website. However, the publisher will likely require that you link
back to the original with a canonical link. A canonical link is an
attribute of HTML that specifies which version of a page should be
preferred in search engine indexing. Basically, while you can
republish the work on your own site, the original publisher gets any
search-e gi e b f la i , a d
post should always rank below theirs in search results.
Furthermore, this approximation of first serial rights generally
prohibits selling second serial or anthology rights, which is not
particularly troublesome as there is no real market for these rights
in technical tutorials.

186
13.1.3 Second Serial and Anthology Rights
In traditional publishing, second serial rights are the rights to
publish a piece that has already been published elsewhere, sold
after rights to the piece have reverted back to you, the author.
Anthology rights are similar, but differ in that they generally do not
have another exclusivity period and may be sold multiple times,
including after first and sometimes second serial rights have been
sold and eventually reverted. These rights generally command
much lower compensation than first serial rights, but they are
essentially free money for writers as no additional work is required
before re-publication.
Technical publishers do not think of second serial rights in the
same way because the industry does not really have a concept of
first serial rights.
Pe le b i i i g a d he a , He , I j
wrote this doc for your competitor I can change a
c le f d a d g ca ha e i f hi ice.
We reject that stuff. Angel Guarisma
In technical content, second serial and anthology rights are not of
particular importance due to the prevalence of work for hire.
Publishers may anthologize their own content into ebooks or other
packaging. Assuming that you sold them articles as work for hire,
you do not have any say in the matter nor should you expect any
additional compensation. You should retain the right to be credited
as the author of the work included or excerpted in the anthology.
Similarly, a third party might purchase anthology, translation,
syndication, or other re-publication rights from the original
publisher, but assuming you sold the article as work for hire, you
are again only entitled attribution, not additional compensation,
unless your contract specifies otherwise.

187
13.1.4 Retaining Rights
In rare cases, you may retain the full copyright to the work and
simply license it to a publisher. Traditional instances of first and
second serial rights are a version of this, as are book publishing
contracts. I am including this note not as an indication that
retaining rights is something that you should expect to happen;
rather, it does exist as an option if it is for some reason important
to you to do so. You should expect many publishers to be reluctant
to agree to publish under anything other than their standard terms.
13.1.5 Online versus Print
Because copyright law originated with printed materials, there is a
distinction made between print and digital copyright. Writers
performing work for hire do not realize any benefits from this
distinction, and neither does the work-for-hire-based
approximation of first serial rights that some publishers purchase.
Furthermore, almost every print publication about technology has a
digital version. However, should you find yourself in the rare
circumstance of writing for print only, inquire as to whether or not
you are also assigning digital rights before signing the contract.

13.2 Software Licensing

The source code you write for an article may be licensed differently
than the article itself. Specifically, I commonly publish some open-
source code on GitHub, which I then sample freely in an article for
a client, selling the client the article but not the underlying code. As
the code is open source, I am thus able to use it in my article. The
benefit of this technicality is that then the readers can copy code
snippets into their own applications without inadvertently
committing copyright infringement, as they are simply adapting
open-source code. This distinction is fairly subtle and may not be

188
explicitly acknowledged in a contract, but considering the article as
the work product and the code as an unrelated exercise in open-
source software saves all parties a potential headache. If you and
your publisher do consider code associated with the article as work
d c , i i he bli he e ibili lice e he c de ha
they publish on their site such that readers can use it.
As a writer in the software industry, it is crucial that you have a
working understanding of open-source licenses. Under the banner
of open-source software, there are several major licenses with
different clauses, and of course several fierce debates about what
constitutes truly open-source software. I prefer to use the MIT
license. I use the Apache 2.0 license if I am releasing open-source
software where I want to prevent other people from releasing the
same software under the same name. These licenses, along with the
BSD 2- and 3-clause licenses, among others, provide
approximately what you would think of as the rights granted by
open source software. You can inspect, reuse, and modify code
released under these licenses, including for commercial purposes.
These licenses specify that the original authors are released from
any liability for the code or your use of it, and you cannot falsely
represent yourself as having written the original code yourself; you
must appropriately credit the authors.
There is another type of open-source license, collectively referred
a c lef lice e . The e e -source licenses function
similarly to the ones we have been discussing with one important
difference: they require any derivative work to be released under
the same license. Many companies take great pains to avoid any
contact with copyleft-licensed code. Like a rootkit written in
legale e, i ca i fec a e i e c deba e, aki g he c a
e ie d c i i la i f he f a e e . A ch, e -
source maintainers who chose to license their software under a

189
copyleft license often explicitly do so to discourage corporate use.
If ae i g e e el e e a le c de i a a icle
releasing your own sample code for a client as open source, ensure
that you are not using a copyleft license.
As a side note, contributing to open source by writing
documentation and tutorials for popular open-source projects can
be a great way to get started and give back to the community.
My next tip and this is also really good for people who
are trying to get in this space is contribute to open
source. The amount of projects that need documentation
igh i h ge a d if e e f he e le h i
illi g each e a d h ld hei ha d , ell if e
willing to do that, it a i e. A a icle i Li
Weekly news came out this week on contributing to
d c e a i i he Li ke el. Tha e e el
helpful, right?! By writing that, you learn to interface with
e le a hi diffe e la e f ab ac i ha e
probably used to working in. Angel Guarisma

13.3 Attribution
Even when you sell work as work for hire, you retain the right to
identify yourself as the author of said work, unless you specifically
sign away said right (known as ghostwriting). If you are ghostwriting,
you should receive accordingly higher compensation. When
writing technical articles for clients, part of the point of the practice
is gaining an audience in your field. Publishers support recognizing
a he a icle a h , f e b i cluding a byline, photo, bio,
and links to your website or social media profiles. Do not give up
this opportunity to build your own online presence.

190
//TODO
1. Review the contract you have with your publisher to
determine which rights they are purchasing to your work.
2. Ensure that either you or your publisher open-sources any
code used in the article so that readers are free to use it in
their own work.
3. If your publisher allows it, you may wish to republish the
article on your own site after the agreed-upon amount of time
has passed. If your publisher requires a link back to the
original article, be sure to include a link of the proper type.

191
Chapter 14: Content Monetization
For publishers, a good piece of content is inherently valuable.
Well-written, relevant tutorials attract substantial, desirable traffic.
Fortunately, there is something of a magic button for turning traffic
into money. Actually, there are several different paths for
converting article views into paydays. The four general categories of
content monetization we will cover are advertisements,
sponsorships, direct sales, and content marketing.
All four of the monetization tactics I will discuss are only effective
with significant traffic. Specific numbers vary by the method and
market, so this is kind of a tautological definition: significant traffic
means that the content has enough views that the tactic is effective.
Publishers spend a lot of time thinking about the unit and overall
economics of their business.
I e ac all h gh a l t about this topic, especially in
the last year while we were being acquired by Digital
Ocean. Scotch was my project for years i bab .
F e a , Al igh , le j i Digi al Ocea a e
much a soul-searching decision for me. One of the
questions that would come up, of course, is should we
ell h ld e kee g i g he e ha e e
taking? It led me to make an analysis regarding: if you
are just a blog, how do you monetize it enough that you
can take that blog and take it to the next level, as far as
income? What I landed on is a blog has one of two
e : i ei he ad e i i g, hich e i cl de
sponsorships, or you find a way to create a product and
then the blog turns into a marketing vehicle. Chris on
Code

192
Knowing how your article will be monetized is an important
influence in the writing process. If your publisher works mostly
with advertisers and sponsors, you can pitch and write with a goal
of attracting and retaining a larger readership. If the publisher
works on a subscription model, they likely care most about reader
engagement and providing consistent value. It is especially
important to recognize when you are working for a content
marketing publication. Articles for such publishers should
showcase some aspect of their product while also providing value
to the reader. For example, when I write for Twilio, I integrate
their products into the applications I am teaching readers how to
develop.
A blica i ei ai a eg i a fac i i e all
perception. One model is not inherently more respectable than the
others, and there are great publishers to write for that use each of
the four models. When creating technical tutorials, we have the
luxury of only writing for reputable publications. Remember that
your name appears above the articles you publish, and thus a
bli he e i a i eff eflec a ell.

14.1 Advertising
The closest publishers can get to automatically turning content into
money is Google AdSense. Ad networks revolutionized online
writing; suddenly everyone had equal access to advertisers paying
top rates thanks to auctions and algorithms. Google AdSense is the
largest such network. Its rates are not guaranteed and substantially
vary by content and traffic type.
Generally, advertisements are sold in units of either CPC or CPM.
CPC C e Click ea he bli he ge aid e e i e
a eade click a ad a d i i he ad e i e eb i e.
Al e a i el , CPM C Pe Mille (La i f h a d) a

193
per thousand impressions of an advertisement. Advertisers bid
differently based on budget and campaign goals. The CPC or CPM
a network can provide is the biggest revenue factor a publisher can
leverage; rates can vary widely based on the region and nature of
traffic. Fortunately, technical content tends to attract substantial
interest from valuable demographics to advertisers.
There are a number of problems with relying solely on advertising
for revenue. Advertisement may decrease the perceived value of
the content, especiall if i i e ed e ad f 5 Wei d F d
Fla e Y S ach Thi Child S a G e U a d Y
Will N Belie e Wha Ha e ed Ne . F he e, a
technical readers do not like websites that serve ads with trackers.
Users may have ad blocking software or other methods of avoiding
those ads, preventing their views of the content from counting.
Finally, there is a lot of bot traffic on the internet and ad networks
relentlessly ensure that only clicks and views from real people are
charged to the advertiser.
Large ad networks often have low cost-per-click and high minimum
payouts. Even though it is easy to register a site with Google
AdSense, if a site does not have enough traffic the publisher might
never see any money. Some networks have minimum traffic
requirements and other invite-only requirements to improve
publisher quality, and they are also more discerning in their
advertisers.
I he ld f ad I e b lli h hi
niche ad networks less Google-style targeted ads and
more unique sponsors. Mark McGranaghan
In tech, ad networks Carbon Ads by BuySellAds and CodeFund,
an independent network, display ads without individualized
tracking technologies, instead relying on the contents of the site to

194
target advertisements at interested viewers. Both networks are
invite-only and readers are likely to see their ads on large,
established publications, open-source documentation, and
technical blogs that are prominent in the community. Niche
networks like these may provide a more reliable and ethical source
of income to technical publications.
14.1.1 On the Death of Advertising
Advertising is not dead, though some wish it were. The economics
of large-scale advertising provide incentives that can make it easy to
run business models that are antithetical to producing good writing.
Niche ad networks, disclosed affiliate links, disclosed sponsored
posts, or direct sponsorship models can in some circumstances
provide the benefits of an advertising model while reducing the
drawbacks, but the present consensus among the professionals
interviewed for this book is that traditional large ad networks are
not a good method for creating a sustainable business publishing
high-quality technical content.
Advertising is bad for publishers.
We e seeing a more rustic approach in the sense
ha e le a e g i g f e clea de ig . The e
cali g back he ad ieal . The e a e ill
publishing companies that have banner ads everywhere,
b he ee be he a e. I e ee a fe cl ed
down over the past couple years. It seems like that stuff
on your site is a sign of rigor mortis in publishing at the
moment. Publishers need to find a way of monetizing
ha i a li le e ble, le a . Peter Cooper
Advertising is bad for writers.

195
 I i i a f ie de a d ha eb h
a producer and consumer of writing on the internet, and
that the writing that actually makes it to you to consume
has a particular economic engine generating it. The
incentives of that economic engine are not your
incentives. Much writing on the internet is written by
machines that are optimized for producing dross at scale.
I would put BuzzFeed, uncontroversially, and The New
York Times, much more controversially, in this category.
This is writing optimized for generating page views to sell
to advertisers. The economic incentives of someone who
is operating on a per page view model are that they will
want to maximize for engagement based on, for example,
clickbaity titles. They will want to have the piece written
by the cheapest professionals they can possibly get to
write the piece. These professionals are probably not
experts in anything in the piece, even if the brand halo of
the organization suggests that they are probably experts.
They will iterate on formulas that repeatedly allow them
to write their quota of pieces every day, with pieces being
strikingly similar to each other. These strikingly similar
pieces are then read by strikingly similar readers for
strikingly similar reasons, but the brand positioning will
be: Oh, , T e da i e i el diffe e ha
M da . Thi de i e he fac ha T e da
ha ba icall del a i i igh e M da
output. Patrick McKenzie
Advertising is bad for readers.
On the business side, I find advertising incredibly
a i fac . I ki d f a bad ba gai all a d
because the users give up a lot: the quality of their

196
 e e ie ce a d hei i ac . Y ca ake ch
money with ads because you need an enormous amount
of traffic for ads to make sense, and the content needs to
be chea l d ced. Tha h ge c e fa .
The e a ea a e f h a f hi ff
because media tends to be a public good, something that
ce i he e be efi a lot of people who are
di i cli ed a f i . I ki d f a c d i ha
respect and a bigger open question on the media front.
Mark McGranaghan
14.1.2 Affiliate Links
Amazon and other sellers offer commissions to sites that refer a
user when that user then makes a purchase. This is somewhat like
an advertisement with a CPC model, but it integrates more directly
with the content. Publishers are required to disclose when they use
affiliate links. Because a purchase from an affiliate link is a rare and
high-value event for the advertiser, the commission a publisher
ecei e i ch highe ha a CPC. A a affilia e a e a ge
from one to ten percent of the purchase price of qualifying
products.
I would point to Wirecutter as the quintessential
example of advertising that nobody gets pissed off about.
Wi ec e i d i g kf . Y g he e a d i
anything, literally toothbrushes! Go to Google right now
a d ea ch Wi ec e hb h a d he ll
recommend the best toothbrushes The e e a billi
hb h ch ice , a d i a e hel i g a f
ch ice. Wi ec e ha ac all d e he k; he e
like Consumer Reports for the modern era. The way
they make money is by getting you to click on affiliate

197
 li k . I d e a , Ad, b hi hb h. I a ,
Oh he e he e i hi hb h a d hi hb h.
The e all affilia e li k . Tha ki d f he de
del ha I hi k e le bjec . Jeff
Atwood
Affiliate links are less common in technical tutorials than most
other kinds of online content. It is hard to connect relevant
products to, say, a tutorial about making Shakespearean sonnets in
JavaScript. Hardware tutorials are a better candidate for affiliate
links. Some SaaS companies offer affiliate programs, but writers
may find more success partnering with such companies directly as
discussed in sections 14.2 and 14.4.

14.2 Sponsorships
Some publishers improve their control over advertisements by
partnering with advertisers directly. This generally requires a larger
publication, or a medium like an email newsletter where traditional
ad networks are less common. Working with advertisers directly is
substantially more effort than integrating with an ad network, but it
offers publishers the opportunity to earn a greater share of the
advertising revenue and retain more control over their site and
content.
As I scaled up and got sponsors, they literally reached
out. Their employees were reading the newsletters and
they were forwarding them to their marketing
de a e . Tha ac all e c . We ill ge
leads because a developer has read our newsletter and
forwarded it to the marketing department and the
marketing department gets in touch with us and says,
Ca e ? We e hea d f engineers that
hi i a g ea e le e . Tha i e e ce fh

198
 people find us our readers recommending us to their
a ke i g e le. The ld each , e d eg ia e.
Over time I kept an eye on what other people in the
email space were doing, not necessarily developers but
other niches where they tend to have a PDF with a media
kit. Then we send that across the marketing departments
and go from there. Peter Cooper
If you have ever listened to an independent podcast, you have
probably heard a eg e he e he dca e
promote web hosts or audio books. After a substantial decrease in
ad revenues, YouTube creators are also increasingly turning to
sponsored content. Sponsorships are not new. Athletes and other
public figures have had public brand affiliations for decades. The
practice requires little adaptation for technical content.
Generally, what the sponsor is paying for is a combination of
di ided a die ce a e i a d a cia i g he ba d
i h he blica i . S onsorships are, if not exclusive on a
weekly or monthly basis, at least limited in number in comparison
to advertisements. Thus, the sponsor has a better chance of
impressing its message upon the reader and more closely connects
itself with the publisher. Furthering the theme of this chapter, the
nature, terms, and value of sponsorships vary wildly from case to
case.
Job postings are a common use case for sponsorships. Email
newsletters, Stack Overflow, and publishers like Smashing
Magazine run relevant job postings alongside more traditional
sponsor messages.

199
14.3 Sales and Subscriptions
When a writer can convince readers of the value of their work,
readers may pay them directly. You have demonstrated this by
purchasing this text. There are a number of advantages to direct
sales: the publisher controls their own pricing and distribution,
their readers pay them directly, and their content stands entirely on
its own, untouched by the needs of advertisers or marketers. This
clear relationship between engaging a core audience and making
revenue is the main attraction of the practice. The biggest difficulty
in direct sales is, well, selling. Most online content, including
technical content, is free. Netflix and The New York Times aside,
people are accustomed to indirect monetization methods. Direct
payment models also require greater trust from an audience.
Content creators who have been helpful on the internet
in this repeated fashion are able to not only utilize the list
f e le he e b il ad e i e c urses or
products they build later on, but also take advantage of
the trust that they have built. Ultimately, if you think
about who you want to learn from and who you trust to
each , i eall ha d g a db ab k f
he bl e. Y e g ing to buy a book because someone
recommended it to you or because the person who wrote
i i a h fig e. I hi k i a eall hel f l
example of how somebody can use writing to build trust
as a means to an end for later on selling something, even
if that other thing is more writing. Courtland Allen
With technical content, once you convince an audience to pay,
they will generally pay handsomely. EBooks on technical topics
generally sell for significantly more than their non-technical
counterparts. For articles, it is more difficult. They do not sell

200
individually, but there are subscription magazines on technical
topics. However, courses and similar information products may be
sold directly and require technical content.
We are seeing people experiment with different types of
monetization, different ways of handling advertising,
he he i ia hi i g Y T be.
Going after the YouTube dollar has a lot of controversy
itself. Publishers are doing signups, so things like
Substack a company doing a lot of promotion around
aid e ail e le e . Tha i e hi g ha e d ,
but they did approach us to talk about it because we have
a lot of newsletters in the space. People are paying three
or four dollars a month to receive these very targeted
iche e ail a d a a e l he e d i g i e ell. I
see them popping up in the media space. If you get a
thousand people paying four or five dollars a month,
e e ch g a j b he e. I hi k e e g i g
see more changes in how things are funded, not
ece a il b b c i i , ha j a e a le. We e
going to see a variety of different things happening
around sponsorship or even companies paying to have
you on as a writer and producing as a publisher and
keeping you employed. Peter Cooper
For frequent, shorter pieces not worth purchasing individually,
subscriptions offer a way for readers to pay publishers for their
content. Newspapers and magazines have run subscription models
for over a century. Sales are one-time revenue, but more of the
revenue is up front, while with subscriptions, the publisher trades
the initial spike for reliable recurring revenue. Similarly, some
creators are able to fund their work through crowdfunding on

201
platforms like Kickstarter or patronage memberships on platforms
like Pa e , di ec l c ec i g hei k hei eade alle .

14.4 Content Marketing

Once you reach a point where your blog has enough
e e ea d e i g l k he e g e , be
sure to look for an outlet or a product that you can
e i e a he ha j a i g, Ok, I g i g
ad be ee e e hi d a ag a h. A lot of people fall
i ha a he he e a i g hei bl g . Chris
on Code
As part of their marketing efforts, some companies maintain their
own long-form technical content blogs as a method of promoting
their products. Digital Ocean runs a popular community forum,
ha he W i e f DO a i g a , a d ha e e ac i ed
third party platforms like scotch.io to increase their reach. Content
can provide self-help customer support, educate potential
customers on the usefulness of an offering, or i eab a d
reputation among developers who might be potential customers or
employees.
Content marketing is especially effective when the advertising is
closely aligned with the value that the readers are coming to the
article for. Rather than showing their product next to unrelated
content on a third-party publisher, or attempting to improve their
brand position with a sponsorship of a publisher in related topics,
the company publishes its own content directly to an audience with
a specific interest rele a he c a c e e a i . The e
benefits do come at the price to the company of operating as its
own publisher.

202
 Your goal is literally to make the users of your
d c feel like he e be e e le. H ca
make them look good in front of their boss?
A company like Twilio is probably a good example of
d i g hi . I e defi i el ee ial f he
showing how to create something that hooks together
certain services and notifies me via an SMS when a
e e g e d . The he ll write a tutorial about that
and obviously it will use Twilio for the SMS part because
he e e ch he l ga e i f d i g ha
a cale. S ill, he ll e lai h d ha a d
c ld i g i a he e ice. Tha he c l hi g
about the tutorial you could put another service in its
lace, b e le ead he ial a d hi k, Oh I ll
actually sign up for Twilio and give this a go and send
SMS. Th e a e he e fec e f ial showing
someone how to achieve a certain end and the end
involves the product but the end is not the product itself.
Peter Cooper
Here is another example. When I write for FloydHub, my articles
always demonstrate code that can be run in a Jupyter Notebook on
their online development platform. The i cl de a R
Fl dH b b ake e eade de a d ha he ea ie
way to follow along with the article is by creating an account and
loading the project, which has the sample code copied in already.
The article also appears with FloydHub branding on their blog and
social media channels. That is it. There is no excessive promotion
within the text or requirement to sign up for an account to read the
article. This is the right way to do content marketing: rely on quality
content, not heavy-handed sales efforts, to drive business results.

203
Generally, content-marketing publications have a specific content
strategy and more narrow field of interest. They do not just want
traffic, they want to engage a specific audience that is interested in
the c a d c .Ac a ide f ech de el e
tools may maintain an engineering blog, which is more often a
recruitment tool rather than a product tool, but is still content
marketing. Excellent technical product documentation is also a
form of content marketing.
In some ways good documentation is what sells a
d c . G d d c e a i i ha ell a API. I
what sells these things that these companies make a lot of
money on. Bad documentation is the reason that people
choose not to use your product. Angel Guarisma
14.4.1 Indirect Monetization
Even if you are not selling a product, publishing can accumulate
long-term value.
Good online content has extremely high equity value.
The Go by Example site is accreting value over time,
even tho gh I ki g i ha ch he e da .
Every year there are more visitors and every week or so
e e e ail e a , Y i e i g ea . S
occasionally I can take advantage of that equity value.
When I was applying for a job a few years ago, people
c ld ee ha I d d e hi k a d a , Oh ha
ki d f i e e i g, he ki d f k ha he d i g. If
I ever wanted to do a business around Go or for
developers or any sort of technical content, I could put
e hi g he e. I e I could put something like ads
ha e e , b ha i ee i g e. T e, he
real value is in the equity, which you can take advantage

204
 of in certain specific, unique ways over time. Mark
McGranaghan
This is especially true for individuals, especially if you are operating
with a readership too small for other monetization methods.
Eventually, this aggregated value coalesces into a personal brand
position.
From a brand-positioning perspective, I think again
technologists tend to be a little bit skeptical of the idea of
having a personal brand or the words brand positioning.
But, if you think of every technologist you respect and
you were to articulate to a friend why you respect this
person, the answer that you are likely to give is a
concrete instantiation of a brand positioning for that
e h e ec . Wh d e ec J h
Ca ack? Well, he ade D a d did hi g i he
c ea i fD ha e e fea f ech ical ge i .
Associating feats of technical genius with someone is a
pretty high-quality brand positioning for a technologist.
The fac ha e e i i gD a d
enterprise software is not essential to how that story is
ld . The e a e i fi i e i he e elf c ld
be deliberate about how you put yourself out into the
world that would not only advance your own interests but
make the work that you do more effective at achieving its
goals. Patrick McKenzie

//TODO
1. Return to your list of ten publishers that you created in
Chapter 2. Identify the way or ways that each publisher makes
money.

205
2. Think about which of the four major monetization strategies,
or what combination thereof, you would want to use if you ran
your own publication and why.

206
Chapter 15: Promoting Your Work
In a nutshell, the ha d a f b ildi g hi g i
ac all b ildi g he hi g ha e i g b ild, i
getting people to use it, getting people to care, getting
people to come to your website when they have literally a
hundred billion other websites that they could choose
from at any moment in time. Why are they going to
come to yours? Courtland Allen
Writing good content is critical to getting people to read your work.
However, no one will read it if they cannot find it. Your publisher
should be putting in just as much effort to promote your work as
their other content, but nothing makes an editor happier than if
you, independently, can make a hit post and direct thousands of
interested readers to their site. If you are self-publishing, whether
for free on a blog or as an information product, how you promote
your work will be a primary factor in its success.
I ll ad i ha he I a a ge e gi ee , I a al
heavily skeptical of the value of marketing, PR, and sales.
I think it is a bug in the engineering community that
e e i i i all ke ical f all f he e hi g . We
build things that make the world a better place. Given
that we build things that make the world a better place,
i fe i al e ibili a e gi ee ac ally
get them adopted or we are not maximizing for the
aggregate impact of the things that we have built.
Patrick McKenzie
Posting on major platforms, distributing via email newsletters, and
speaking at conferences and meetups are all active methods of
promoting your content. You can also use an array of search
engine optimization tactics to gather organic hits. You do not have

207
to promote everything on every channel; experiment until you find
reliable success and stick with that approach. Regardless of how
you promote your work, use metrics to analyze the effectiveness of
the approach.

15.1 Platforms
Your publisher (or your own website) hosts your content, but you
still need third-party platforms to give it reach and discoverability
beyond your original audience. Regardless of the platform, it is
important to develop an understanding of what its users want and
tailor your submissions to each community rather than treating
each one like a uniform RSS feed. Diving into any large online
community can be overwhelming.
N , i 2020, I hi k e e eei g he i ac f e e
human being being online and every human being
sharing their opinions about stuff it can be quite
e if i g i agg ega e. Fi f all e e e ed. If
a thousand people tell you what they hi k, he e j
no sane way to process that information. No human
being, in the history of human beings, has really talked to
a thousand people in one day in a meaningful way. I
mean that was essentially impossible, even if you wanted
,b i the norm. Jeff Atwood
When promoting your work, act like it is the early 2000s and surf
the web; stay on top of the wave of views. You will have to try a lot
of things knowing that not all of them will work out, and failures
can feel very public. Success can be even scarier when your work is
being viewed by thousands of people in short order. Either way, it
i a f he ce f a i i i g k i ac .

208
15.1.1 Hacker News
Hacker News is the number one source of high quality traffic of
software developers and related professionals available on the
internet today. It is the sort of place where, if Stripe posts a product
announcement that makes it to the front page, one of the founders
will respond to comments from their longstanding personal
accounts. Getting to the top of Hacker News is worth, depending
on the headline, 5,000 and up (and I mean way up) page views
from interested professionals. Even bottom-of-the-front-page posts
(hit top 25 but not top 5) get one or two thousand views. Patrick
McKenzie, writing from the handle patio11, has been a Hacker
News user since its early days and remains near the top of its all-
time leaderboard.
At one point I was the number two user on Hacker
Ne . I igh ha e li ed d be h ee . I
think that people underrate Hacker News massively. I
think there is a meme in the community that Hacker
News threads are populated by toxic commenters and
that it is a ceaselessly negative place such that the world
would be better without Hacker News in it. I think
unequivocally Hacker News is an extraordinary venue
for value creation throughout the world, largely by
bringing together technologists who would not have
otherwise met each other. There are people who make
lifelong relationships from that site. I met my former co-
founders there; Thomas Ptacek is one of my best friends
for life; and it feels extremely unlikely that I would have
my current job but for Hacker News. I think you could
say that for many people who are nowhere close to being
quote-unquote on the leaderboard.

209
 Hacker News helps disseminate ideas, like my ideas on
sales and engineering career optimization and the body
of practice that is dealing with venture funding, both
from the startup side of the fence and from the investor
side of the fence. These things would be difficult to get
access to unless you had a high-quality social network
that already had an expert about them in it. It is basically
one step short of miraculous that you could find George
Grellas, who is an expert Silicon Valley lawyer practicing
for thirty years, and have George Grellas patiently walk
you through the impacts of the changes in the
independent contractor classification in the wake of
Microsoft abuses in the 1990s. By the way, George
Grellas was a practicing lawyer for Microsoft. That I
could read that as a person who was newly an
independent contractor working in central Japan in the
late 2000s/early 2010s is one step short of miraculous.
I ll ack ledge ha he e a e ce ai h ead ha a e
generally low quality, mostly things that are removed
f he c e i e e f he ech l g i d .I
not a particularly great watering hole to talk about
politics, for example. But, for the things it does well,
Hacker News does them better than plausibly any place
in the world . I i h e e le h c ld ge al e
out of Hacker News were active there. Patrick
McKenzie
The Hacker News moderators recognize the value of this resource.
Do not be fooled by the simple interface; the platform runs
sophisticated and secretive anti-spam technology to protect against
spurious submissions and vote rigging. I would recommend
browsing the site for a few days and participating in a few

210
comments sections before posting your own content to get a sense
of the community and what practices are acceptable.
Articles and tutorials are best submitted as general link
submissions, but if you have created a product or something more
b a ial ha e le ca i e ac i h, e he Sh HN ag
be listed on a secondary page with much less competition. Show
HN submissions can still make it onto the main page with sufficient
upvotes. Regardless of how you submit your work, leave a
comment on your own post that provides additional context that
might be of specific interest to the Hacker News audience. Do not
summarize or rephrase the post. Instead, focus on providing
additional value and kickstarting a discussion, as discussion is very
ef l f hel i g i e he a fe f he Ne ab
to the main ranking.
The Hacker News audience can be famously critical of most work.
Do not let pointed comments get to you; the majority of comments
on an honest submission should be constructive. Engage in good
faith with people offering genuine feedback and ignore other
comment threads.
15.1.2 Reddit
Reddit is a content aggregation and commenting platform divided
into countless subreddits, or communities dedicated to specific
topics. These subreddits vary from a few hundred to several
million subscribers, though the larger technical subreddits generally
operate in the hundreds of thousands range. The most important
factor for finding success with a Reddit post is only putting it in the
one or two most relevant active communities, even if they are not
the largest. It is better to get moderate sustained, interested traffic
than a brief spike of disinterested browsers.

211
Across the entire site, Reddit has significantly more users than
Hacker News. However, Reddit traffic tends to be more casual in
nature. Furthermore, Reddit as a community tends to look down
on people who only promote their own content on the site. If you
are going to post your articles, you should probably also make an
effort to join the discussion on other articles of interest on the
forum. Many subreddits explicitly ban self-promotion of any kind,
be e check each b eddi le bef e i g i.
15.1.3 LinkedIn
LinkedIn is a professional platform for maintaining a network
de ig ed e ee e eal-world connections and help them
to develop new contacts. It is also a popular platform for
promoting content, but in my experience skews more toward
business and introductory technical articles. Your feed will depend
substantially on your network. I know many of my connections and
followers on LinkedIn, and I have a correspondingly high
engagement rate on my content; it is not only interesting to my
connections on its own merits, but also because I wrote it. I check
LinkedIn regularly to see what my connections are posting because
I find interest there for the same reasons.
LinkedIn distinguishes between connections and followers. When
you connect with someone, you automatically also follow each
he , ea i g ill ee each he feed.
However, you can follow or be followed by someone without
connecting with them, and you can unfollow people you are
connected to without losing that connection. Depending on the size
of your network and the degree of connection between you and
someone seeing your post, LinkedIn might present that reader with
either the option to ask for a connection or a button to follow your

212
account. Thus, I have had to rely mostly on connections to build
up a modest readership of a few hundred people on LinkedIn.
15.1.4 Twitter
Twitter is a very popular platform among developers for promoting
products, open-source projects, and technical content. I have not
personally had much success with wide reach or engagement on
Twitter, though admittedly I have not yet invested substantial effort
in creating an audience on the platform. Fortunately for us, Daniel
Vassallo has made that investment, increasing his audience from
150 to 24,000 followers in 14 months.
The value of Twitter is mostly to share a journey as it is
ha e i g. I hi k i a e diffe e e f elli g
ha he e i i g a bl g , hich e d be a
e ec i e. The ical bl g i Thi Yea i
Re ie ; e e d fall i l f hi d igh bia . I hi k
the magic of Twitter, what makes it work, is that for both
the writer and the consumer you are sharing as it
happens. This is a habit I formed: pretty much every day
close to the end of the day is my Twitter time. I try to
eflec ha ha e ed ha da a d hi k f hi g
that my audience might find interesting, and I share
them. I think they like following something as it is
happening if it has some interesting aspects to it.
Some tweets go a bit viral, and they end up bringing with
he e f ll e , hich ca e ike . I d
intentionally try for viral tweets l I j sharing
ih e ec a i . I i g i agi e ha
a die ce ld fi d i e e i g .M a eg ha bee
mostly just to keep it simple not to over-optimize it, just
to share. Daniel Vassallo

213
15.1.5 Niche Platforms
There is a long tail of aggregators, chatrooms, Facebook groups,
and forums in niche interests that can bring modest but highly
engaged traffic. Like dealing with subreddits, it is important to
develop an understanding of which platforms and communities will
find your work interesting. With niche communities, having a good
understanding of how the platform operates and community rules
is essential to making a post that attracts audience interest rather
than administrator action. Go narrow. Go deep. People who care
about your domain will find your work.
[Curators] I work with and I are familiar with the top
blogs and the better sources of news for certain areas,
a d eg h e a d e kee a e e he . I a
i le a ha . I like i h Dja g f e a le.
Y e babl g ing to know what the most interesting
Django sites are and who the people are in the scene.
You keep on top of that i ea ea . The e le el i
social bookmarking and social sites. There are people on
Twitter who always like the right stuff or retweet the right
stuff or sites like Hacker News or Reddit he e e l f
similar kinds of places, including tech sites like lobste.rs
f e a le . We e j l ki g a ie b al
going into the comments because a lot of stuff gets
surfaced there ha e le d ice if j ick
he f age f hi g . The e a l f eadi g d ,
b ha a he a f fi di g c e . Peter Cooper

15.2 Email Lists

I ran a Ruby blog called Ruby Inside that became really
popular in the mid-2000s and so I had many contacts. I
saw what was going on in the industry with email,

214
 especially with things like Groupon. Everyone was just
getting interested in email as a way of delivering
ifica i , a d I h gh , Wha if I c ld d
Ruby news, but do it via email? Someone else is going to
d hi , le d i fi . Peter Cooper
A fe ea ag , I ld ha e e ed hi ec i ih a
be i ed, b N , i i idel k ha e ail e le e
offer some of the highest rates of engagement of any form of
promotion. When people sign up for your email list, they are
doing so with the expectation that you will provide valuable content
for free with the occasional sales pitch mixed in. Unlike a platform
on social media, you own your distribution with your email list.
Y ill l e eade d e a cha ge i e e el e
algorithm.
Wi h e ail, f e, i he e gage e ha eall ell
e i . Tha ha g e i i iall i h i : I c ld e d
an email to 1,000 people and then I could see that 500
of them clicked on a site that we link to or that we
i e . E ail c a d highe CPM a d beca e
ge ha e gage e , i a i le a ha . Peter
Cooper
15.3 In Person
As I am writing this, every in-person conference, user group, and
meetup that I know of has been cancelled or delayed until further
notice due to the global COVID-19 pandemic. In the interest of
writing something that will still be useful in a few years, I will not
focus on the present or try to predict the future. Instead, consider
this section as an explanation of how this kind of promotion
worked through February 2020, and then apply its lessons to

215
whatever version of the world you find yourself living in when you
read it.
The basics of conferences and meetups are similar and vary mostly
in scale. A bunch of people, 10 to 10,000, get together in an
appropriately sized room. Some of these people are designated as
speakers and give prepared talks at specified times. As a
conference attendee, you have the opportunity to talk to people in
your industry who you might not otherwise get the chance to meet,
but this benefit multiples substantially if you have convinced the
conference organizers to invite you to be one of the speakers and
have put in the effort to create a useful talk.
Conference speaking was probably one of the best things
I did for promoting my books. It was good because I was
able to continue to work on my voice. I was able to
travel, which was really awesome, by speaking at these
conferences. I was able to test out my material. Some
material that is in the books was actually tested as
conference talks first. I gave a talk at about ten or so
conferences before I actually started writing the book.
Getting on stage was really terrifying for me because I
actually suffer from no small amount of social anxiety,
e hi g ha i ig ifica l be e ha I ed
speaking on stage. The initial few times I spoke on stage
were absolutely terrifying and very much out of my
comfort zone. It was such a great way to share the stuff
ha I d d e, b i g he b k c fe e ce , alk
e le i e ,a d e a e ial ha I glad
that I pushed through my fear to become a conference
speaker. Tracy Osborn

216
Going out in person and engaging with the community will help
you increase your profile and find out what people actually want to
learn about, improving your work and your ability to sell it.

15.4 Metrics
Without accurate measurement on meaningful figures, there is no
way for you to know if your promotional efforts are working. If you
are writing for a publisher, they will have their own metrics and
may or may not share how well your article performed. If you are
the publisher, setting up analytics on your site is an essential step.
Before setting anything up, consider what you want to measure.
This will mostly depend on your monetization model. Everyone
needs to measure the essentials like page views, time on page, and
traffic origin. Advertising-based sites, and to a lesser extent
sponsorship-based sites, generally want to collect more data on
their users, a controversial practice to say the least. However, many
advertising-based technical publishers sell advertisers on interest-
based information about their content, not their readership.
Subscription sites care about paying subscriber counts, signups,
visitor conversion rates (what percent of visitors turn into paying
customers), and subscriber churn (what percent of subscribers
unsubscribe over a given period of time). Content marketing
operations care about the same, but with a degree of separation as
they have to analyze how their content affects these metrics on their
actual product, and the content is only one factor in each metric.
Free and featureful, Google Analytics is the most common
analytics platform. With minimal configuration, it can give any site
basic insights into any of the above metrics. You and your users pay
for this service with your data and privacy. As such, many users run
extensions to block trackers like Google Analytics, which reduces
the accuracy of your measurements. Once you have the revenue to

217
justify the expenditure, depending on your needs and site
architecture, you may want to integrate one of dozens of paid
analytics solutions. If you do so, I would encourage you to choose
one with a focus on user privacy.

15.5 Search Engine Optimization

The only reliable way to be ranked high on a fair search, regardless
of the algorithm used, is to provide a quality response that is
relevant to the query. Google is certainly a gameable system, and
there are a number of techniques you can use to subtly boost your
chances. In general, the best long-term move is to write excellent
content that people like to read.
For Scotch, we did a lot of SEO work, and really SEO
starts with g ea c e . A he e d f he da e e j
lucky that Google is sending us traffic. If Google changed
their algorithms, which they have a few times over the
last few years, traffic could drop and that would be
everything.
In our business, SEO is absolutely king. Ninety percent
of Scotch traffic does come from Google. Chris on
Code
When promoting what you made, do not lose sight of why you
made it in the first place. A focus on good content over SEO will
keep you moving toward your goals.
The only person that you really need to satisfy is yourself
a d ha i i gl diffic l d .M e le e d
the rest of their lives trying to understand how to actually
a i f he el e . I a diffic l j b be fai . B , if
start out with that intention I d i g hi f e, if
a b d ead i , g ea , b I d i g hi f e

218
 beca e i e hi g ha I eed d then I think
ha he a eg ha h ld ha e. I a i i g
a eg beca e i bei g e elf. I the long
ha all he e i . Jeff Atwood

//TODO
1. Write down three platforms where you would like to promote
your work. Try to include at least one niche forum.
2. Ask your publisher what they do to promote your work. Also
ask if they are willing to share page views and other metrics on
your articles.
3. If you publish any of your content yourself, develop a plan to
build your own audience over time.

219
Chapter 16: Long-Term Engagements
A wide range of options exist outside the world of writing two
thousand word articles for publishers. Projects of a more ambitious
scope might come from a client suggestion or from personal
inspiration. For example, you might discover that there is a
reference book missing and decide to write it yourself. If some
format mentioned here piques your interest, I encourage you to do
more research into its specifications and market. The process of
brainstorming, market validation, finding a publisher, finding
sources, writing, and editing any length of work will rely heavily on
the same skills you learned in Act 1 and will have practiced by
writing articles.

16.1 Books
If you have an idea burning a hole in your pocket that is way too
big for an article, you might be looking at writing a technical book.
These kinds of books vary in length, but I would say you should be
looking at writing at least twenty thousand words, plus substantial
sample code and original graphics, which may be screenshots or
diagrams depending on the contents of the book. On the long end,
there are technical books and computing-related textbooks well
over a thousand pages in length. Regardless of length, the most
difficult part of scoping a book is figuring out what to leave out, a
process I wrestled with many times with this book.
M b k a e eall all. I k there are lots of
differing ideas about this, but for me personally, a good
article length is 2,000 to 4,000 words. Hello Web App is
18,000 words and Hello Web Design is 28,000 words, so
compared to some of the big published books, which are
babl he de f 100,000 d , he e i e a

220
 bi h e . M e i a , I hi e hi g ha i
h elli g? I a aki g a l fi c ea da
job with WeddingLovely, and I needed to supplement
my own income, so I needed to work on projects that
c ld b i g i c e i . I a c bi a i fk i g
that I had just enough to make a book but not too much.
I wanted a short book that would be something that
people would want to buy. Tracy Osborn
Short books still deliver a lot of value.
[The Good Parts of AWS] was intentionally supposed to
be a summary and aggregation of information, to
condense as much information as possible. The book is
split in two parts, a high-level overview in the first part
and a technical guide in the second part. For the first
part, I originally thought that I would end up with a few
e age . Agai , I did a i e ff
graphs or some other nonsense just to fill in the pages.
Daniel Vassallo
16.1.1 Working with Publishers
While I advocate for writing two thousand word articles for
publishers, the considerations regarding books are more nuanced.
The non-financial aspects of working with a good publisher remain
the same; they provide structure and accountability in the writing
process and bring specific expertise to the final product, helping
you develop as a writer and create your best work. Unlike for
articles, where you are paid a fixed price for a relatively small time
investment, writing a book can take from several months months to
several years with a somewhat uncertain financial upside. A well-
known author or recognized expert might pitch a book idea and get
a publishing contract and advance right away, while a lesser-known

221
writer may have to substantially develop the book on their own
before pitching it.
Much digital ink has been spilled on the exact process of writing a
book about programming. I have linked a few such posts in the
sources for this chapter (see Appendix C). Ultimately, the process
looks a lot like writing ten or twenty articles with the same editor
and then publishing them all at the same time. These posts also
discuss the financial outcomes.
There are many reputable companies that you should consider as a
potential publisher. Factors for consideration include audience,
audience size, editorial process, topics of interest, royalty rates,
other contract terms, and industry reputation. In sum, you have to
think about all of the same things you would consider when
selecting a publisher for articles, but you have to be more careful as
this is a larger commitment. Before signing with a publisher, talk to
a ece a h ge a e e f he bli he ce .
16.1.2 Self-Publishing
This book is self-published. Doing so is also possible and often
profitable for purely technical books as well, but self-publishing
requires a substantial time investment in things outside of writing
like market research, editing, formatting, payment processing, and
audience building. Printing your own books adds several more
substantial expenses and logistical hurdles. For a comprehensive
guide to the process, I recommend Authority by Nathan Barry.

16.2 Series
Some topics are too long to cover in a single article, but too short
for a book. If you have an idea that falls between these two,
consider writing a series. A series can be as short as two articles or

222
as long as you and your publisher agree to make it, but the most
important consideration is how the topic is divided.
The way I like to break it down is: can you create a path
to building an application by using a bunch of different
articles and piecing them together? Can you basically
create a road map from articles? I like to think for
elf, if I ha e d c e ed ne of the steps, then I
should write that as its own article and then kind of link
them all together. That means, if it can be broken out
i i a icle, I ll d ha beca e I e f d
that, especially for SEO, people will need that single part
of it and could find it helpful. Chris on Code
You want to make sure that each article in the series feels like a
complete work that would be valuable to a reader on its own, as
many readers will encounter your article while browsing to learn
about a specific topic or resolve a given error and will not want to
start at the beginning of a series just to give your solution a try. Self-
contained runnable code samples in context and a complete
introduction and conclusion help articles in a series stand alone.
I try to stay away from series. I find that not very many
people go and complete the entire series. Just like if a
person comes to an article, they only want a couple of
c de bl ck f he f ll a icle i a ha d bala ce, f
sure. With our courses, once I started making courses, I
learned that every lesson should be compartmentalized
somehow. If somebody finds a single article or a single
part of a series, it should be able to stand alone, even
h gh i a f a e ie . Tha e f he hi gs I
think not many people do. It takes more work, definitely.
Chris on Code

223
Outline the entire series before pitching it. You will want to sell the
entire series to a single publisher, though you may need to do so
one article at a time.
16.2.1 Columns
If your desire to write a series is based on an interest in being a
regular contributor on a specific topic over an indefinite period of
time, and you are able to stick to a regular schedule, you might try
writing a column instead of a series. Columns are not common in
the tech world outside of consumer tech publications; they are a
carryover from mainstream media like newspapers. Columnists
generally have a decent amount of flexibility in what they write
about within their domain and are a regular fixture of the
publication.
16.2.2 Courses
A series of video lectures, screencasts, live coding sessions, or
written components, combined with a clear plan of learning,
assessment, and accountability, is generally packaged and sold as a
course. As with articles in a series, creating clear divisions in the
topic and maintaining a steady pace is important for engaging your
audience. Unlike series, courses can assume that the audience is
willing to start at the beginning and work through the course
linearly, though each lesson should strive to be individually
valuable.
When I outline a course, I definitely try to make it so
ha each a c ld be i a icle. Le a I a
creating a React application. One of the videos would be
React routing, and it ld j be, He , he e h
e e g i g add he Reac e , a d he e h
e eg i g e he Reac e. Y d eall

224
 need to know how the other pages or the other
components were made, you just need to know that
e e i g c e . The le a e e
c ea i g a ab age. Y c ld a , Le c ea e a
c ac f i Reac , a d he ha c ld a d al e.
Designing a homepage for your application? That can
stand alone. Chris on Code

16.3 Alternate Formats

This is a loose collection of other artifacts that you might want to
create or a client might ask for. Each of them is in some way a
larger engagement than an article or requires additional skills,
equipment, or credentials not mentioned elsewhere in this book.
16.3.1 Academic Papers
Academic writing has an entirely different style, context,
publication cycle, reward structure, and goal than the business-
focused publishing that is the subject of this book. Academic
publishing focuses on disseminating information about original
research rather than teaching a discrete skill or creating marketing
content. A great deal of academic publishing in computer science
happens through conferences rather than journals, and the process,
which involves a period of peer review, is generally much slower
than a traditionally publishing a work of equivalent scope.
For a peer-reviewed publication in particular, there are a
few things that are important. The general level of rigor
and clarity expected are higher. An important part of the
acade ic adi i i ha e acc e i g hi c f
ka d he ld. I i a ha b ild
prior work, show how your work relates to that prior
work, and explicitly cite prior work where relevant. Often

225
 you see people writing blog posts and making wild claims
alki g ab he i k, b he d ece a il
link to the prior papers. There is an explicit process of
peer review where you send this article out to people
who are experts in the field who can provide feedback,
and you make some amount of adjustments to the article
based on that feedback. Eventually people agree that the
paper is good to go. Mark McGranaghan
16.3.2 Whitepapers and Case Studies
Whitepapers are beefed-up articles written for a narrower
audience. They can approach an academic tone but are still
designed to be instructional. A technology company might issue a
whitepaper to describe a novel system they have developed or
explain some technical insight in their product. A few years ago,
when it was popular to release blockchain-based digital currency,
launches were often associated with whitepapers describing the
technical implementation and structure of the new offering. Do not
let this tainted association discourage you from creating a
whitepaper. It is an article with better market positioning to suggest
its relatively higher value and staying power.
Another form of article with good branding is a case study. A case
study analyzes a single system or event to draw broader insights.
They are very popular in business schools, where students may
read and write case studies on specific business decisions.
Generally, a case study spends a lot of time establishing exact
context and explaining a chain of events or providing a complete
description of a system. It then extrapolates learnings that the
reader can apply to their own situation.

226
16.3.3 Videos
Video really works for some people. As a consumer, I prefer
reading text, but there is a large audience for filmed technical
content. Video takes longer both to produce and consume than
text and requires more equipment and software to create and edit,
but it has an accordingly higher perceived value.
Originally with Hello Web App I was just going to write
the ebooks and a paperback. I want to say the first
Kickstarter did i cl de ide . Righ bef e I a g i g
to launch it through the Kickstarter to people who had
preordered less than a month before launch I was
eadi g e a icle ab h if e elf-publishing a
book, you should always have video. You can sell the
videos for much more than the book and your overall
revenue is going to increase. That actually held true for
me. After launch something like 70 percent of my orders
were for ebooks, but 70 percent of my revenue came
from video. The first round of video I never got any
complaints about this but my first round of video was
very rough. I literally just used my MacBook Pro and
regular old headphones, and I built my web-app and
reviewed the book. But, when I saw how much people
liked those videos, I bought a new camera and a new
microphone. I re-recorded everything to make the videos
higher quality once I realized the value of having them.
Tracy Osborn
Video also provides the opportunity to make chronological guides
showing the order of operations in creating an application.
Video skimmability is definitely a little more difficult
than writing. You can put timestamps in the description

227
 to let people maneuver around, basically creating a table
f c e f he ide . Tha ha de d ha i
writing beca e d ha e h2 ha gi g all e
the place.
Wha I e f d he d i g ha i ha a l f g e
a h ld ki d f j d all f he c de, He e
he HTML, he e he CSS, he e he Ja aSc i .
Whe e b ildi g e hi g ha eall h i
g e .Y a , Oka , I g i g add hi a f he
h l, I g i g le i i h CSS, I g i g g back
he HTML, a d I g i g g back he CSS. I
ab ci g ac be ee a b ch f la g age . Tha j
how we build things naturally. That is far harder to do in
articles than it is in video because in video you can
bounce between the two seamlessly; in articles you have
to take your final demo app and start cutting it apart in
random places so that you can guide a user through the
process. Chris on Code
Video can also be the key to making content on different topics
than text allows for.
When I first started making videos, it was just to make
j ke . I e al a l ed aki g j ke , b I j ke
them to occasional tweets or amongst friends. Then I
h gh , I hi k hi ide bjec i f , I ll d i . I
downloaded a video editing app and I found out it was
f . S I decided, I ll h i T i e , The i
got really popular. The next week I thought of another
joke I could make in a video, and people really liked it. I
ke d i g i af e ha . I f be able ha e he e
jokes and pitfalls and fun things that a lot of developers
face. A l f de a e e d e le a d he d

228
 wand to show that they struggle as much as they do.
Cassidy Williams
16.3.4 Speaking
Like video, speaking is a radically different format from an article.
Conference talks require substantial preparation but can later be
used as inspiration for a series of articles, a book, or a course.
C fe e ce alk , f e, a e elli g. I e d e i e
a lot of conference speaking not so much the last year
or so, but there were a couple of years where I was at 15
or 17 events a year. There are two different kinds of
c fe e ce alk . The e a c fe e ce alk a d a
conference keynote. The keynote is more storytelling.
The e g i g be ea f ac al ake-aways
f a ke e, b la gel e he e i i e
people, get them hyped for the conference, get them
emotionally involved. Conference talks or panel
discussions have to have this fine balance of storytelling
with a lot of take-aways, but also in a format that is really
down to earth and friendly, at least for my kind of talks.
Tracy Osborn
To insert more technical content into your talk, consider live
coding, where you perform a coding exercise or create an
application live in front of your audience.
I love doing live coding talks, mostly because everyone is
like, ha e if i g, j like j aid. I a f
a he a die ce. Wha f ab li e c di g i
ha i a g ea a eall ill a e a c ce a d a
you can do this too. Look, if I can do this in front of a
giant crowd of people, clearly you can do this from the

229
 comfort of your own home. That really drives that kind
of point home. Cassidy Williams

16.4 Jobs
If you find the writing processes especially rewarding, you may be
interested in working in technical content full-time or seeking larger
freelance projects. Even if you are an exceptionally prolific and
well-compensated author with a large client book, it is difficult for a
f eela ce i e ake a ch a a a da d f a e e gi ee
salary. There are a number of roles, which are not particularly
standardized among companies, that have writing as a major part of
the job responsibilities.
As a full-time editor or staff writer, you work primarily for a single
publication and both produce and edit content. Since most
publications rely on a large roster of freelance writers to get more
variety of content for less money, in-house editing jobs are limited.
However, some companies maintain large writing teams for a mix
of public-facing technical articles, documentation, internal
documentation, and technical writing. When companies opt not to
make this investment, their ability to create technical
documentation is cyclically hindered.
There are still places, and you read about it on the Write
the Docs Slack all of the time, that employ one technical
writer who is responsible for web development, Twitter,
and all of these other things. These writers are absolutely
miserable.
You build a technical writing team because you have an
e gi ee i g ea a i g, We eed d c e a i .
People need to know how to use these projects, and we
eed k h b ild a d c e a i ea .

230
 People go right away and look up how Google built a
documentation team or how Amazon built a
documentation team, and they end up not building the
documentation team that is right for them. So, you have
these documentarians who are really good at writing
tutorials on code, who are seeing job descriptions that
l k like he e ab i i g f c de, he he eali
i ha he ga i a i ha a al ed hei eed f
technical writing. You get these technical writers put in
ii a d he he lea e beca e he e b ed.
The , he ga i a i hi k, Tech ical i i g i ha d
hi e f , a d We d ac all eed hi beca e
e ll ha e he de el e i e hi .
The e a giant, gaping hole of knowledge that is not
being disseminated outside of groups that are writing
technical documentation. There are a lot of places that
are doing the right work, but there are a whole lot more
places that are not giving this profession, I d a
say respect, because I think that sounds a little too
entitled, but the seriousness consideration that it
deserves. Angel Guarisma
Some companies without a writing staff will contract freelancers for
larger projects like documenting an entire product. I have been
offered projects like this before, but I have not yet accepted one
because of the time commitment required. From what I can tell,
these projects are quite substantial in scope and generally require
developing a deep familiarity wi h he c a d c bef e
the writing begins.
In many companies, jobs where the main responsibility is writing
d call he le a i i g i i . Ti le like de el e
e a geli a d c i a age i l ha he le e a e

231
at the intersection of engineering and business to, among other
responsibilities, create, edit, and promote technical content to
achieve business goals.
[A ] Ve I had a d al le he e he e I a b h a
software engineer and a developer evangelist. A
developer evangelism role is a combination of
e gi ee i g a d a ke i g, he e e a e gi ee
a a ke i g ea e a a ke e he
engineering team. The role involves speaking at
conferences, going to hackathons, and participating in
meetups to show de el e , He , e ha e hi API,
h ld e i . M e j b af e Ve a he
same thing. I was going to conferences, hackathons, and
ee a d a i g, He e i hi c de, he e h
e i . I a ale , b de d like bei g ld ,
and so I had to learn a lot of nuances of selling to
developers and understanding developers. Cassidy
Williams
Regardless of the title, most full-time roles in technical content
development include responsibilities beyond creating as an
individual contributor. Working with freelance writers, setting
content strategy, and evaluating tangible metrics and results are all
common responsibilities of this category of job. While your
understanding of the craft of writing might land you one of these
roles, your ability to execute in the business of writing may be a
stronger determining factor in your success.

//TODO
1. After writing a few articles, preferably across two or more
publishers, think about what other formats you would be
interested in exploring.

232
2. Remember to use your skills in idea validation, research, and
outlining before committing to a large project.
3. If you want to work with technical content as part of your
regular job, start by looking for projects at your current
employer that offer the opportunity to write.

233
Appendices
Thank you for reading Writing for Software Developers. As you
made it this far, you will probably enjoy the full edited transcripts
of every interview, presented in Appendix A. If you are looking for
the blank version of The 9 Questions Worksheet from Chapter 1,
l k f he ha A e di B. F a li f hi b k ce ,
consult Appendix C.
For more on programming and technical content development,
read my essays at https://philipkiely.com/essays and my work for
clients at https://philipkiely.com/essays/posts.html.

234
Appendix A: Complete Interview Transcripts
I recorded the following interviews and then transcribed them by
hand. The transcripts have been edited for clarity.

Courtland Allen
Courtland Allen is the founder of Indie Hackers, an online
community of independent creators and bootstrapped business
operators. For the community, he produces high-value technical
content in the form of interviews with successful independent
founders that include concrete information like revenue numbers.
Courtland shared his expertise from conducting over five-hundred
interviews and his experience using technical documentation while
building the Indie Hackers forum software himself.
H li icall , a fi i h, ha a ach d i g
interviews?
I e ie i g i e a ha cie ce. I a a ha I ha e
particularly studied, other than to practice it myself. If I had to
describe to you my approach, rather than describing an approach
ha I ha e i i d, i ld be fig i g a ach a I
telling it to you.
T icall , ba ed he edi ha I c d c i g he i e ie
over, which is a podcast, people are going to actually hear my voice.
That affects how I interview people because listeners quite frankly
get tired of hearing the same voice over and over and over again. If
I was doing interviews for a magazine, or doing an interview where
d eall ee e, l ead a d ee he e ha I
alki g , he I d be fi e. Beca e he li e e a e hea i g
voice, I try to minimize my presence in interviews as much as
possible. I want the other person to be doing the talking; I want

235
every episode to h ca e ha e .Id a he e i de
showcase my repeated opinions over and over and over again,
because quite frankly it will get kind of boring.
My first rule of thumb for myself at least is to try to come up with
questions that allow the other person to talk for a while, that allow
he h ca e hei e e i e, ha d eall e i e e
ee he e i de i a a ic la di ec i . I g i g be
doing any editorial afterwards, so the interview is just going to be
showcasing the subject.
The second thing I would say is that a lot of the interview comes
down to the person that you select to be on the show. Quite
frankly, there are people for whom anyone could interview them
and it would be a great interview, and there are people that the
ld be i e ie e c ld i e ie a d i ld j be a
e ible i e ie . The e l ch ha ca eall d
get the most out of your guests, because at the end of the day the
spotlight is on the guest, not on the interviewer. I put a lot of work,
especially recently, into trying to select guests who I think will be
entertaining and confident, well spoken and charismatic, and easy
to listen to, and who actually will have relevant things to say that are
novel and that the listeners will find insightful. A lot of interviewers
d f c a ch g e elec i . I eall ea f c
what you can do as an interviewer to get the most out of the guest,
b I eall hi k ha l a be e hi e ce f he
equation.
How do you think preparing this sort of high-value long-form
content, like these interviews, helped you build the Indie Hackers
community?
Oh, it was absolutely crucial. In a meta sort of way, talking to so
many founders over the years and learning how they built their

236
businesses combined with my own experiences trying to start things
with varying degrees of success and failure give me a very healthy
respect for marketing and distribution. In a nutshell, the hard part
f b ildi g hi g i ac all b ildi g he hi g ha e
i g b ild, i ge i g e le e i , ge i g e le ca e,
getting people to come to your website when they have literally a
hundred billion other websites that they could choose from at any
moment in time. Why are they going to come to yours?
With Indie Hackers, I knew from the beginning that I wanted it to
be a community. I wanted it to be a self-sustaining network of
people who could help each other and provide support, but I also
knew that nobody was going to come to a community just because I
created it. I needed some sort of valuable thing to get people in the
d . O ce he e e he e I c ld he a , He , j i hi
c i . I k e ha I ld ha e g i l l e he
course of years before it reached the critical mass where the
community itself would be its own selling point. For me, in the
early days, that looked like interviews. I found entrepreneurs who
had done this rare thing of building a tech business by themselves
without raising funding, just living off the product, and I asked
them all sorts of questions about how they were able to do it.
I wanted my interviews to stand out from other interviews. I wanted
my website to be particularly captivating, so I made sure to get
e e b d e e e be . Tha ea ha i e f e
e le ha I a ked i e ie aid , beca e e le d want
to share their revenue numbers. But I only interviewed the people
who said yes. I was able to build up a repository of great interviews
that went super in-depth and were very helpful to a level that other
i e ie e e . Tha ga e he i e l ad of traffic. Literally! I
had hundreds of thousands of page views in the very first week that
it was out. That traffic converted to newsletter subscribers who

237
received a newsletter of interviews every week. Because the
newsletter subscribers built up an audience that I controlled, it was
easier for me to get the community off the ground once I built the
f .Id hi k i c ld ha e bee d e if I had a ed i h
he i e ie , le I d f d e he eall c elli g
distribution channel to try to get people in the door.
Had you created much technical content (technical = nonfiction
that people use to do things) outside of these interviews?
Nope, this was my very first crack at doing any sort of publishing or
content of any kind.
Within the Indie Hackers community there are a lot of people
working on a wide variety of companies. Are there any patterns
that you see in how people in your community use the content that
they create effectively?
I think a lot of the people that I talk to start by producing content.
The patterns that I see are people produce content with kind of the
a e ai ha I had i h I die Hacke . I all he e d i
and of itself i a ea a e d. I hi k he e eall aki g
advantage of the fact that content is extremely easy and compelling
to share. When you write something that resonates with somebody,
he e e likel c he li k a d ee i e ail i hei
f ie d e da e e age a g e hi g. I a g ea
way to build up an audience.
The ge e al a e i , H ca I l d ce c e , b
produce content in a medium or on a platform where those
readers will then turn into my subscribers? Then, later on, how can
I b ild a b i e ba ed he e e le ha I i i g f ? Of
he e e ha c e f ha , I hi k fa i e e i : be
hel f l he i e e . I hi eali a i ha e f he be

238
c e ca ide, he he i ech ical i i g ad ice
even inspirational stories, should be content that empowers the
people who read it rather than merely answering a question, trying
to provide your own viewpoint on things, or other self-focused
content.
I ll gi e a e a le: I e i e ie ed f diffe e e le h
are online course creators. Almost every one of them had a
significant component of how they got started by creating a Twitter
acc . The j a ed ee i g hel f l i ab hi g he d
learned about coding, for example, ways to achieve certain things in
your editor or a particular programming language. People follow
he e acc beca e he eali e c i e l ha he , hi i
e hel f l i f a i , a d if I f ll hi e ,I g i g
lea a d bec e a be e e elf. Thei f ll e
them to give good advice.
These content creators who have been helpful on the internet in
this repeated fashion are able to not only utilize the list of people
he e b il ad e i e c e d c he b ild la e ,
but also take advantage of the trust that they have built. Ultimately,
if you think about who you want to learn from and who you trust to
each , i eall ha d g a db ab k f he bl e.
Y e g i g b a b k beca e e e ec e ded i
you or because the person who wrote it is a trustworthy figure. I
hi k i a eall hel f l e a le f h eb d ca e ii g
to build trust as a means to an end for later on selling something,
even if that other thing is more writing. I think that the biggest trend
ha I e ee i a f c aki g e hi g hel f l.
Once the person has built up that authority in their network or in
that community, if that thing is content-ba ed c e ha e

239
talking about, where do you see the line between content that
should be free and content that should be released as a product?
I gh beca e i diffe de e di g he a ic la a die ce
ha e i i g f a d iche ic ha e alki g ab .
Generally, my advice to most people is to make as little as possible
free. Where the line usually gets drawn is people make things free
he he e i e di g g hei a die ce, a d he ake
hi g aid he he e i e di g ake e . S e hi g
are easier to grow, others are easier to use to make money.
F e a le, if e d ci g a c e ha a ge ed a
ab l e begi e , i g a h ge a die ce beca e e le
are beginners. There are always more beginners than there are
intermediate or expert people, so your course has a huge audience
f e le h a e eall ha e i . A he e d f he da ,
he e babl le likel b a hi g beca e he e
i e ha e i . The e a e a l f he , ha a eall g ea
opportunity to give something away for free because you know
e g i g ha e a l f each. Y k babl
ld ha e ade ha ch e a a , a d i a g ea a
to grow your brand, build trust, get people to know who you are,
a d a be ell he la e ih e hi g ha e
profitable.
I e ee a l f e le d ha . We B , f e a le, i e
big on occasionally doing things for free. Even some people who
a e c e c ea , like Ta l O ell, (he a c ea f he
Larval framework for PHP) build a lot of stuff that they sell, but
they also build a lot of stuff for free to give back to the community
and allow them to grow their audience. For Otwell, a lot of things
that he does for free are things that he knows he can get a lot of
ba g f hi b ck f. He ll do something for free if he knows

240
he ll be able d a l f alk ab i i e a bl g ab
i.I be hi e-and-done thing because it will actually help
him with his goal of growing the community and proving that he
has this goodwill.
There are a lot of considerations, but generally what it comes down
i ake e hi g f ee he i g i g be ha fi able,
hel g , a d aid he i e hi g ha ha high
potential to sell for a lot and is targeted at a more limited audience
ha e e c fide ill ac all b .
A he hi g i hi c i ha I e iced i ha he
No Code movement has a large presence on Indie Hackers. If
ea ki g a N C de l i e i g ell a
API or other developer tool, how might your approach to technical
content change in that situation?
S e a i g if a ell a N C de l, h ld
write content to help you market it?
Yeah, in contrast to the standard practice of developer tools, like
Twilio, and how they do content.
Tha a e i e e i g e i , a d I ha e ee a f
examples of it. I can only really name off of the top of my head a
couple people who are building No Code tools and promoting
them using content. My intuition says that you would be very
education-focused because quite frankly developers are not new.
Pe le ha e bee c di g hi g f ea , a d if e ii g
content for something like a Twilio or a Stripe, you have to do a lot
of education becau e i e f a kl de el e eed lea . I a
different kind of drier education, where you sort of explain the
API, explain the design considerations, and explain how to
integrate this tool with other tools.

241
With No Code I think the bigger opportunity is not in educating
the people who are already experts, but rather in empowering
e le h a e i e a a e ha hi i e e a hi g. The a ke
f e le h c ld bec e N C de a d e a e i a
times more massive than the market of people who are No Coders.
The e j i g lea a e l. M f h e l ,b
virtue of being No Code tools, tend to have their own
documentation.
F e a le, if e i g each e le h ake Ai B B
without code, you might instruct them to use Zapier and Airtable,
but the fact of the matter is Zapier and Airtable are other
companies that have their own documentation on how to use their
products and you can lean on that. Your role in that particular
i ai ld be e h ha possible, show how this
can be done, to a broader audience, rather than explain to people
exactly the ins and outs and what you think of using certain tools.
Le a e eb d h ac all b il e f he e e
ecific N C de l , like ve built Zapier. Then I think the
equation changes a little bit, you have to educate people on how to
use your tool, and there are so many philosophies on how to do
that. I interviewed Vlad Magdalin, the creator of Webflow.
Webflow is arguably a No Code tool. Their philosophy is that they
d a b c e he c de f you have to learn CSS to
be able to use Webflow effectively, so their documentation is very
i ila ech ical d c e a i . The eali e ha he e i i g
for a No Code audience, he e like, Ok, he e ha
d ih CSS. I a a he e eachi g h c de
hile e i g hei l.
S e hi g like, I d k , Za ie , ca ge b ih
lea i g h c de. Y d ha e iea hi g on Zapier

242
that explains how to write code. They have some features that are
f ga e , b he e e iall d each ha ki d f
ff a d ha beca e i a i eg al a f hei l. I
matters a lot what kind of tool you built. In general, when I look at
N C de, he e a e a e le h d k ha hi i
ible. I he e ea l da i al like 2010 i h
Bi C i . I g i g be ch bigge i a he fi e e
years, because so many people are going to be building interactive
apps and websites. People are going to be looking at it as this low-
hanging-fruit. Most writing should be educating people and
i i i g he , a d i ce e he e ha i i ed he ,
capture that traffic and utilize it to your advantage later on.
A he e I i e ie ed, A gel G a i a, aid I e
a g dd c e ai i ha ell he e hi g ha he e
companies make a lot of money on. Bad documentation is the
ea ha e le ch e e d c . What are your
thoughts on that?
Totally, I think a lot of products spread through word of mouth,
especially in the developer community. Simply put, developers are
elli g each he , He , hi API i g ea hi API ck . I die
Hackers is owned by Stripe. Stripe has traditionally grown a lot
through word of mouth because developers like the
documentation, the ease of use of the product. I think there a lot of
products where decisions are made in a top-down instead of a
bottom-up approach. Some manager, some director, or some
CTO a , Oka , e e g i g e hi a d f ce i
e e b d . B f de el e d c , i bec i g i c ea i gl
bottom- . De el e ac all ch e hich l he e g i g
be working with, and if you want your tool to be adopted, it means
the developers actually have to say good things about it. That

243
means the documentation has to be good. I completely agree,
documentation is the thing that tanks your product or makes it.
I N C de i i e e i g beca e I ot sure what the long run
i g i g l k like. The e a e c a ie f ll f N C de
right now i d e e i a a fe i . I e e .S h d
No Code products spread? Do they spread via word of mouth
because people are using them and they get together in No Code
circles and recommend those tools to others? Maybe. But since
e ei ch a a ce e a a be N C de d ha e h e
ci cle , he ca effec i el ead ia d f h. N
Coders have to use marketing channels. I think there could be
some differences, but in the long run I assume they would coalesce
i he a e a a l f de el e . I ha d ake
predictions about the future.
During the process of building the technical side of Indie Hackers,
what was your experience of using online documentation and
tutorials?
I a e ch b he ea f a . I e bee c di g i ce I
was a kid, so by the time I sat down to write the software for Indie
Hackers, I was pretty comfortable with all of the tools I was using. I
a e c f able i h de el i g f he eb. I did eall
eed ead a l . I d e e b il a li e f , b I i i i el
grasped the building blocks that needed to go into it I spent maybe
a little time looking things up and reading documentation.
The one exception is the framework that I was using, which is
E be .j . I a al e a i e f A g la Reac f b ildi g
modern interactive web applications. I was a little bit newer to
Ember, so I spent a lot of time interacting with their guides, their
content, and their APIs, figuring out how to do particular things. As
I built the forum, I would adopt new services. For example, I use

244
Postmark to send notification emails, so if somebody responds to
he f e g i g ge a e ail. Tha e h gh
P a k API f a ac i al e ail. I d e e ed P ak
before, so I dove into their documentation to figure it out. I would
describe it as pull-ba ed e f i gd c e ai .I a
really reading anything in advance to get an overview; rather, I was
just coding and encountering particular problems and things I
wanted to do. I looked up APIs and documentation on a need-to-
know basis to help me get over various hurdles or implementations
ha I had i le ented before.
When you reached for a piece of documentation during this
process, how did you go through it to see whether or not it would
answer your question?
For me, because I was technically competent enough to guess how
most of these tools would work, I would go to the APIs and
command-F for some term that I was looking for. I also did a fair
bit of googling, but generally once I found the API reference, I
would skip any of the broader guides and look into the APIs to see
where I could do things. Every now and then I would find myself
on GitHub, using client libraries or something that someone had
created and skimming through. I would describe it as extremely
impatient skimming, trying things, seeing what would work, and
mostly making educated guesses until it worked. I was going as
quickly as I possibly could based on whatever little information I
could read online. Again, this is something I could only do
successfully because I mostly already knew the shape of what I
wanted to do and how these tools would work. Years ago, when I
first started coding, if you had asked me that question the answer
would have been very different. There was a lot more in-depth
reading and a lot more trying to get an overview of how everything
worked, and then after I had that overview, I could build up

245
confidence and go into the right places. I did much less skimming
and much less guess-and-check.
Chris on Code from scotch.io talked about skimmability. As a
highly experienced software developer, what aspects of an article
for a piece of documentation do you look for to increase the
skimmability and make the piece more useful to you?
N be e, I a h ge fa f ha i g a API efe e ce, hich I
think is pretty much standard practice by now. I love it when an
API reference is all on one page. I love to be able to go to one
i gle age a d be able e he b e b il -in find and page
fea e ea ch f ha I a . I d a ha e click a
bunch of different links and not be able to search because
everything is under different pages. That for me is huge.
Number two, I like seeing the coding samples in a sidebar. This is
super helpful because I can read the code and the description of
each e d i e e calli g i l a e l . S e i e I a b
looking for a code block and looking at the text with that;
sometimes I start by looking at the text and only then looking at the
code block. I think having sensible organization is great. Under
headers, including sub-headers that make sense and keywords
followed by descriptions is really helpful for readability. Sometimes
ca ge ha e i g ge j b eadi g he c de
block, so the headings will help with that. Also, those subheadings
a e a g ea lace a d ke d he e e de cribing
h he e h d k . The e ca h he I d i g
find-on-the- age ea chi g f e hi g. If e ii gS i e
API documentation and you have the concept of a customer,
a be e e igh ea ch e .

246
Jeff Atwood
Jeff Atwood is the i e f C di g H ( e f he i e e
longest-running and most popular technical blogs), co-founder of
Stack Overflow and the Stack Exchange network (one of the 100
highest-traffic sites in the United States), and co-founder of
Discourse (a provider of open-source forum software aiming to
improve the state of online communication).
Discourse reimagines internet communication, so what do you
think is wrong with the way people are communicating on the
internet today and what would you like to see in the future?
One of my main recommendations for startups and people that I
talk to is that they should be regularly communicating with their
c e a d hei e de a d ha ha e i g. I hi k
one of the worst things that you can do as a programmer is to get
ivory tower syndrome, where you never actually interact with users.
Programmers are just so unrepresentative of the average user that
he e d b ild hi g ha ake e e he , b d eall
make sense to the broader public. Reg la e le d ake
e e da a d hi k, Ya , I ca ai i i f f
c e all da . The i ic hi g i ha i ha cha ged a li le bi
with the smartphone era; there are a lot of people who are actually
pretty excited to get up and spend all day messing with their
phones.
When I started in 2013, or 2012 really, my main observation was
that there was no free, open source software that let programmers
talk to their users that was actually good. There was no software
that you would want to use, that felt good to use, that was easy to
install, and that had a good user experience. There was a lot of
really classic forum software that was really terrible it reflected the
norms of the web from 1999 and it had barely evolved. The initial

247
impetus was that we just want modern software that I can give to
programmers who can use it to talk to their users, their customers,
their audience, and their fans. The act of having a community on
the web was to me so fundamental and instrumental i ha the
eb a ed be. The eb i ab ge i g hi g d e, i
ab ha gi g , i ab bei g cial, b i al ab
collective action.
F e a le, I a chi g hi h Ne fli called D F***
i h Ca , a d i i e e i g because a lot of it is about how
people used Facebook and forums to track down this person who
a h i g a i al c el . Tha a i 2010. I ha I call he
da k a e he B ie f he i e e : i Faceb k
( hich ca e e a id a hi i ) b i he al e a i e
internet, that is more real, more direct, more authentic. I love that
part of the internet, so I wanted that to flourish, and in order for
that to happen there had to be really good open-source software.
That was the igi al i e . N , i 2020, I hi k e e eei g
the impact of every human being being online and every human
being sharing their opinions about stuff it can be quite terrifying in
agg ega e. Fi f all e e e ed. If a h a d e le ell
y ha he hi k, he e j a e a ce ha
information. No human being, in the history of human beings, has
really talked to a thousand people in one day in a meaningful way.
I mean that was essentially impossible, even if you wanted to, but
i he .
You can go on Twitter, post something, and a thousand people
might respond to it, depending on the visibility it gets. Today, I
hi k ha I eall hi g f i b eaki g a a he e la ge
communities into smaller ones because the h a i d ca
i e ac i h hi a e le. I g e a be if e a celeb i ,
b l k a celeb i ie , he a e a e. I ea f he

248
 deal i h hi a i e i fl f a e i ei he , beca e i j
not normal. I think today i e e ali e he idea ha
everyone can interact with hundreds to thousands of people in a
da a d I d hi k he h a i d i eall ca able f ha . I
think it breaks you at some very basic level to even try it.
My vision of Discourse these days is to break things down into
alle , e kable i f c i . Tha a ha
he he big hi g ca e i h ld e i . I hi k he
should, but we should really moderate our use of them. I used to
look very askance at the idea ha Oh, cial edia i like ki g
ciga e e , e e all e ll de a d h heal h ha i . I
the 1930s, the 1940s, people did not think that smoking was
heal h , i ead he h gh , Oh eah, ki g, g ea ac i i .
Feels good, smoke all a (la gh ). I a l la e ha
medical professionals figured out that there were these really
debilitating health effects from heavy smoking. I think that is where
e e g i g ge ih de a di g f cial edia.
You really need to limit how you do it, you need to limit your
exposure to it, and you need to limit the other people involved.
Limits, limits, limits. The idea that free, unlimited, every-human-
connected-to-every-other-human twenty-four-seven communication
sounds good in the abstract in reality is kind of a fucking
igh a e. I ca e a l f ha . Le b eak hi g d i
smaller, more manageable units. Discourse is a piece of that where
you can be as big or as small as you want to be be, and it also
belongs yo .I e ce: i d e bel g Ma k
Z cke be g, i d e bel g T i e , i d e bel g e
other big company. It belongs to you and you can do what you
want with it.

249
You have the forum, but then your forum needs content. Do you
think technical content can bridge that gap that you were talking
about? How can you make content that encourages its readers to
use it productively?
I think the more technical and narrower the topic, the better your
odds are. If you start a forum ha all ab Ta l S if , ae
c i f a b i beca e he e a e a l f e le h ha e a
opinion about Taylor Swift. Politics are worse. Anyone can have an
opinion, and many people do, so the more technical and more
specific you can be for communities of interest, the more
e e d l i hel beca e e e e iall a i g he
a die ce. Y e aki g e he e le he f ha e ha
ha ed i e e . I j Oh, like e , ell g e
ha I like e . S ei e e a ej b ad, a d e
going to attract too many people. If you look at the Stack Exchange
e k, j S ack O e fl b all f he he i e , he e
all based on very narrow-ish technical topics, so everybody has that
in common. Tha b h a a al li i e a d al a i ce i e
attract people. That definitely works: narrow your focus, be very
ecific. I hi k i g ea , i ha S ack E cha ge d e , I e al a
been a fan.
Y e i e ab S ack E cha ge bei g a iki, within these
communities at the level of the post. What makes this individual
wiki entry or post useful?
Well, i ab he ble ha e l i g. I hi k i ha be
a ble ha a licable e e le ha j . Thi i
something that people struggle with on Stack Overflow. Their idea
i Well, i j b hel e, a d hi i e i ab gi i g e
a e . I eall . I ab gi i g a b ch f e le a
a e, j e. I ha e ble i e e e a i e f a

250
problem that other people are also going to have, and it has to be
approached in that manner. You have to be thinking not selfishly
but selflessly; explain this problem and that helps not just me but
everyone else that has this problem. Now to be fair, there could be
some super narrow problem that only one person will ever have,
but in reality most problems people run into a fair number of
i e , a d i be ca ha c ce a di i da
e a i g.
I a highe ba , a d e le ge set about it. They complain,
H da e hel e ih ble ? Wha I a i gi
that you have to show us why your problem matters, and you also
have to put in the work. Are you explaining the problem, did you
do a bunch of research, can you give us a minimum reproducible
version of your problem, and have you fundamentally done the
work to demonstrate that this problem is interesting and useful? I
think those are also implicit lessons of Stack Overflow that people
still struggle with. I think if you want that kind of help, you need to
g a diffe e i e. The e a l f ggle i h ha i hi he
network.
I like he idea ha h ld be able g Wiki edia a d
write whatever you want. I mean maybe, but it has to be notable.
Wikipedia has its guide of notability, meaning it has to be
e hi g ha fi e e e e le ha j . Y ca
write a Wikipedia entry about your dog, for example, because even
though I know you love your dog and your dog is probably very
swee , ha d e ea d g eed a Wiki edia e .
The e a diffe e i e f ha .
Whe ea a h i i g ech ical c e , ha e d
both sides of the work. Not only do you have to provide an answer

251
but you first must pose the question and prove its importance.
How does that process differ from a question and answer process?
Y ha e be able e lai he ble e l i g fi .
R bbe d cki g i hi cla ic ech i e he e ake e
i a i a e bjec a d e e d i s a person and you explain the
problem to that inanimate object. A lot of times, not all of the time,
b al f i e ll ac all fig e i beca e he ce f
talking to this inanimate object and just explaining the problem in
some rational way gets you pretty much to the solution. I love posts
like that. Those are some of my favorite posts on Stack Overflow.
The e e e ie ce i I ge e a ed a e i , a d I k e i had
to be really good because Stack Overflow has these really high
standa d . Wi h hi ce f bbe d cki g, b he i e
e e lai ed he ble , if ill ha e he ble he
babl ha e a e g d e la a i f i . I likel
have a minimum reproducible version of it and the conditions for
it. Th ha e a e g d e i a ha i . I all a
eall ef l e e ci e, e e if d e d i g he
question.
B he a , I g i g a l gi e a e f ha i g high
a da d . A l f e le ell e Y a da d a e high.
M e e i , If a l e a da d , j g e he e
el e he i e e .
You have ads on your site, Coding Horror. In the past in interviews
e aid, I el c a l ad C di g H . B i
worked out. What forms of content monetization do you feel are
acceptable and productive in the modern internet?
I would point to Wirecutter as the quintessential example of
advertising that nobody gets pissed off about. Wirecutter is doing
kf . Y g he e a d i a hi g, literally toothbrushes!

252
G G gle igh a d ea ch Wi ec e hb h a d
he ll ec e d he be hb he The e e a billi
hb h ch ice , a d i a e hel i g a f ch ice.
Wi ec e ha ac all d e he k; he e like Consumer
Reports for the modern era. The way they make money is by
ge i g click affilia e li k . I d e a , Ad, b hi
hb h. I a , Oh he e he e i hi hb h a d hi
hb h. The e all affilia e li k . Tha ki d f he de
del ha I hi k e le bjec .
I also think people are so addicted to getting stuff for free that they
ill le a e a a i hi g a f ad BS. I j dgi g. B
e le al d de a d h ch he e giving up when
he a , If I ge hi f f ee, I ka i h all f he he ff
ha c e i h i . I d hi k he eall a ecia e h ch
he e ac all gi i g i he a iacal i f f ee. I g e i
just human nature, but it leads down some pretty dark paths. It also
leads to complete centralization on the internet because the easiest
and most painless way to do stuff is to have one enormous
c a ha j d e e e hi g f . If l k i Chi a, i
like WeChat and Tencent and all that stuff. They have one app
that they do everything in. I do think there is a stronger argument
to be made for not having everything centralized. Discourse is
about decentralization at a very deep level, and I think the ad story
is very very i ila . The a ha ala able e le i
definitely the approach on Wirecutter. I use Wirecutter all of the
time. It works for me. So if you want to think about responsible
ad e i i g, ba icall j c Wi ec e . Tha
recommendation. The e a e he a , b ha ha I hi k
works best at the moment.
At the craft level, what can other writers learn from the book Code
Complete by Steve McConnell?

253
The main thing that was really illuminating about the book is that
i i e i hi eall h a e. I ab M b ai i
bigge ha . I e ab he ce : h d e a age
this process to minimize the human element of error? How can
a age he h a ele e fe a d i ake ha g i g
to be in every project, and how can you understand the weaknesses
ha e a a h a ? B I ea e e e. We all ha e
these personal failings. We all have pride attached to our work that
may be misplaced. We all want to think of ourselves as perfect
people. But in reali , e e . I a e i e e i g ha he
book attacked the human side of the problem rather than telling
h i e e fec c de. I did a , J f ll he e
c di g g ideli e a d ll i e e fec c de. The a ach a
more about how to manage your own psyche how to manage your
own emotion ch ha e ca able f d ci g be
work. I thought that was a very deep, deep message, deeper than
programming. Also very, very true: programming is people.
If you have a team that is all pissed off and hates each other,
he e g i g i e e ible c de. I d ca e h ale ed he
a e, if he e ad a each he , i ed ff, ha , i j g i g
to be bad. That was the key insight of Code Complete for me:
programming is the art of dealing with people. You think of
programming as the art of dealing with the computer, but the
c e i e ch hi d b, d b achi e. I ea
deal i h he c e . F he a , ha diffic l i deali g
with other people, your team, your manager, your project, and the
e le h a e f he jec . Tha he eall
diffic l a a d ha he a ha he b k eall del e i . I
does talk about code, but it spends a lot of time talking about
personal character and the emotions of the people on your team
a dh ha e a ai able jec ha b eaki g he
people working on it. I still love those topics. Those are timeless

254
 ic , a d ha h i ch a g ea b k. Tha h i d e
ever eall ge f da e, beca e e le a e g i g cha ge
for the next ten thousand years, not in that way. In a hundred years
e ll be i g adicall diffe e li g, b e le ill ill be
i ed ff a each he . I ll ell ha i h e-hundred percent
certainty.
How have your opinions on writing online changed since the early
says of Coding Horror?
First of all, blogging has essentially died. I think short form has
destroyed everything else. You still will find people writing essays
and blogs he j a e ea l a acce ed a d i eaf a
as it used to be. You had Tumblr, which sold and is now a sad,
shambling shell of itself, but that was short-form blogging. Twitter is
effectively short-form blogging; they increased the limit from 140 to
280 characters. I think that things are just getting chopped into
i ie a d i ie iece , hich i g bad, b ha he
c e eali ha e li e i . I e ha a e fi d e le h
iee a .M e a e e e e ha l g. I a i i g ha
ch, a d i ha d f e iea ch a e. I ha e
diffic l da i g bl g, i ha d gi e ad ice hi .
These days, maybe if you want to reach people, make a TikTok
video. I see some very funny TikTok videos that are out to educate
e le. Y k ha , a be he e igh , a be if a
reach this vast amount of humanity, video is your form. Not just
ide b ic ide , e e ai i g ic ide . The e f
all of this stuff, but the audience has changed. The audience is so
big a d ide . Be ee 2010 a d 2020 e l ki g a a
radically larger number of people online and a lot of those people
a e g i g ha e he a ie ce ead a Pa l G aha e a .
Some will, but it depends who you are trying to reach. The answer

255
to that has really changed over time because everything has become
so pervasive. Everybody carries a smartphone in their pocket, and
e eachi g e h ge e ce age f h a i ha
ee eaching at all before.
Id k he e ac be , b I e h a d a d
thousands of people still read your work every day. What do you
think brings them back to it?
I i g i e ab hi g ha a e , He e ech l g
of this particula ea . Y e i g elf ch e
ecific bi f ech l g a d ecific bi f i e. Y e
looking at the more timeless aspects of the underlying principles,
the underlying human factors. If you look at my early blog, I did
write about some very technical stuff that now seems completely
i le . I igh ha e a e ed f like a ea , b b d g i g
ca e ab ha a e. Tha fi e. If l k a he
e ha eall a e , i ab he dee e h a i e f h
we get better at doing this as people. How do we become better
versions of ourselves? The job is to help other people, and
yourself, become better versions of themselves. And that means a
l f diffe e hi g . If a i e ff ha g i g last,
ha g i g ha e a l g helf life, a a id eall
meticulous, detailed, in-depth technical stuff because it has such a
short shelf life in the big picture of things.
I write the stuff that you say is dead, and there is a lot of demand
for it online.
I d e ha e de a d. If i hel f l a d eache a ble e le
a e ha i g i h c e ech l g , i g i e ha . Y
have to mix it up, though. You have to write a variety of content.
Some percent of your content can be current technology and
another percent should be relatively more timeless things about

256
how to run projects, how to deal with people, how to deal with
emotions things that are more about sustainability in your career.
For every post you write about stuff tha ha e i g hi ea , i e
a ha g i g be ele a e ea f .T i i
, a d kee a g d bala ce g i g. I a i gd ie
about current technology I ba icall he h b h gi l.
Why not both?
Y e a i g he internet is really big now, bigger than it used to
be. How do you find the small niche areas that still operate in this
a e bee alki g ab he e e le a e g i g ead hi
long-form stuff?
I ab e abli hi g a e a, a d e a belongs to you.
Y ca i e ab ha e e i i e e i g .Y d ha e
to follow any particular formula, you just have to be yourself. I
think people respond to that. They can see who you are, and they
ca ee ha e i e e ed i . If start doing stuff that
d e e ee h a e like I g i g f ll hi
f la, like I d eall like i b I k i g i g gi e e
SEO or some shit like that i g i g i g fal e, a d e le ca
see that. I think long-term, people d e ec he d
ha . The ca ee ha e chea i g, a d j i g f ll a
f la f cce . The ca ee ha e eall ca i g
ab ha e i i g. Y e j d i g ha hi k he
people want you to do, or SEO, or who knows.
The l e ha eall eed ai f i elf a d ha
surprisingly difficult to do. Most people spend the rest of their lives
i g de a d h ac all a i f he el e . I a
difficult job to be fair. But, if you start out with that intention I
d i g hi f e, if a b d ead i , g ea , b I d i g hi f
e beca e i e hi g ha I eed d he I hi k ha he

257
 a eg ha h ld ha e. I a i i g a eg beca e i
being t e elf. I he l g ha all he e i .
Id hi k i ible be cce f l i g be ii f
ha hi k he e le a be. I d hi k i
possible to be successful trying to be your vision of what the world
wants you to be. Just follow what you like and be really inquisitive.
Try to mix it up I will say that. Try a variety of different things to
de e i e ha i i ha like. Tha d e ea d he a e
thing over and over or do only explicitly what you like, but find out
what you like, try different things, try them on for size, and then be
honest with yourself and your audience. In the long run, people
will respect you for that.

258
Chris on Code
Chris started scotch.io with his childhood friend Nick Cerminara to
publish articles and courses on front-end development. In late
2019, Scotch joined Digital Ocean and Chris took a role at the
company as a web community manager. Chris generously shared
his time and expertise from scaling Scotch to 4 million monthly
page views and publishing content from 500 guest authors. He had
great things to say as soon as I answered the phone and was kind
enough to restart with the microphone on to begin the interview.
It sounds like you were about to say something very insightful and
I d like hea i .
I want to start off by saying that I really like the idea [of your book]
and I totally agree with it, and everything that you just said: there
are a lot of technical people out there but there are not a lot of
technical writers. I think that every resource that gets put out,
including this book, if it can make just a couple more writers out of
developers, is good for everybody.
Thanks for that. I was hoping you could start out by giving me a 2-
minute history of scotch.io: how you started it, how you scaled it,
and what attracted you to join a larger team.
Sure. I started Scotch with my co-founder, who is actually a
childhood friend. We were coding, and I think a lot of coders find
this problem: they are looking to solve one of their coding issues,
and they look online and the solution is not online so then they
spend hours trying to figure it out. To me, it felt like Scotch, when
it started, was kind of an affirmation journal. It was more for me to
lidif ha I d lea ed. Eventually, it turned into a lot of people
i i i g he eb i e. B ildi g a bl g i ea , e eciall he e da
with how many people are writing, and I absolutely love it, but it

259
took a while to build that much traffic, about eight months from
when we first started to when we got more than like ten viewers is
he i eli e. The e defi i el ha ea l g i d ge e , b ce
that hit I think we saw a lot of growth in the traffic.
From there it was really fun to see the amount of people that found
our articles helpful. Many of them were trying to get into technical
i i g, e a ed he g e a h g a . We e had
over five hundred people run through the guest author program, all
edi ed b e a d a c le f he e le. I bee f o build
hi c i . Tech ical i i g i e ha j a ial; i
connecting you with teaching somebody across the table from you
a d ha ha I l e ab i.F begi i g , e g e he
blog to be a pretty solid size. By the time we got up to about 4
million page views per month, it was really fun.
The c l hi g ha I ll a , he e alk ab he a i i
Digital Ocean, is that Scotch has always been hosted on Digital
Ocean, because we believed in them from the beginning. They
helped us start our websites and our technical careers. Everything
that Digital Ocean did was similar to the Scotch mentality: they
have a solid blog and they invest heavily in the community because
they know that developers helping developers is good for
everybody. When they reached out, it kind of made sense because
e e ha f e d ide f bl ggi g. The e g he backe d ide
covered, too. Together I think that we can do a lot of cool stuff.
What makes a technical article good?
It all depends on perspective. You have to pick your goal per
tutorial. For me, picking tutorial goals is interesting because
sometimes I want to get a quick tip out so that people can visit the
article, find the code snippet that they need, and get out. That way
their project can keep on moving along. If they can find it and get

260
 ha he eed i hi 30 ec d , ha cce f ha a icle.
There are other types of articles where we do far more long-form
ech ial . The e a icle a , He , d ha e a c le
hours? Le b ild e hi g ge he . Le ake e a d ,
f jec . F e, h e a icle a e e ch lea i g jec .
As I think about different archetypes of articles, I have my own
classifications. Do you have a classification of article according to
goal?
Our main separation is between theory, which is not an article that
you can actually create something with, but more of an article that
help you understand the concept, and practice. Theory and
practice are the two that we differentiate between. At Scotch we
had a category called bar talk, which was simply news. The second
category is tutorials, and within tutorials we have theory and
practice. Within that, there are other small tags like quick tip,
which is an article that you read in about 30 seconds, or real-world
project, which is the longer form.
Once you have your archetype, how do you deal with topic
selection? How do you figure out what to write about?
Al f i i i fl e ced b ha I d i g i e al jec ,
and a lot of it is influenced by a certain timeliness to articles that
help them gain traffic. If Svelte has just come out then you write
about Svelte for a little bit. I think that what a lot of people do is
start by trying to figure out what projects would make a good article
topic, but I try to break it down a little further than that. Ask,
Wha i a g d jec ? a d he , Wha a e he c e
ha ake ha g d jec ? The , I b eak d e e
component into its own article so that people can try to piece
together one, two, or even three articles.

261
We started Scotch with a lot of these simpler articles: how to do
form validation in Angular, how to do it in React, how to handle
e e i i V e. The , e g a i he e e aid, Ok,
le d these really cool long-form articles, where we would do,
H B ild XYZ i h Tech l g 1, Tech l g 2, 3, a d 4.
What we found was that a few people read and followed through
on those articles, but far fewer than the broader-term articles. In
our business, SEO is absolutely king. Ninety percent of Scotch
traffic does come from Google. We had a pivot back to the
broader sort of articles and only do the long-form every once in a
while.
O ce e elec ed he jec , h d fig e he c e
of he a icle a d he c e f he a le a lica i eg i g
to put in there? One of the things I struggle with the most is trying
to figure out which pieces of an application or concept will be most
critical to a reader and which I can leave out in the name of
simplicity.
Yeah, ha a e gh ggle ha cha ge e a icle. The a
I like to break it down is: can you create a path to building an
application by using a bunch of different articles and piecing them
together? Can you basically create a road map from articles? I like
hi k f elf, if I ha e d c e ed e f he e , he I
should write that as its own article and then kind of link them all
together. That means, if it can be broken out into its own article,
I ll d ha beca e I e f d ha , e eciall f SEO,
people will need that single part of it and could find it helpful.
Do you take longer applications and then break them into series?
I try to stay away from series. I find that not very many people go
and complete the entire series. Just like if a person comes to an
article, they only want a couple of code blocks out of the full

262
a icle i a ha d bala ce, f e. Wi h c e , ce I
started making courses, I learned that every lesson should be
compartmentalized somehow. If somebody finds a single article or
a single part of a series, it should be able to stand alone, even
h gh i a f a e ie . Tha e f he hi g I hi k
many people do. It takes more work, definitely.
What do you do in order to make that happen?
When I outline a course, I definitely try to make it so that each
a c ld be i a icle. Le a I a c ea i g a Reac
application. One of the videos would be React routing, and it
ld j be, He , he e h e e g i g add he Reac
e , a d he e h e eg i g e he Reac e. Y
d eall eed k h he he age he he
c e e e ade, j eed k ha e e i g
c e . The le a e e c ea i g a ab age. Y
c ld a , Le c ea e a c ac f i Reac , a d he ha
could stand alone. Designing a homepage for your application?
That can stand alone.
You mentioned before that you tend to draw your ideas from
personal projec ha e ki g . D ha e a f al
methods of turning these projects into articles?
Tha a g d e i . The e a a lice f i e he I ied .
When I was building a side project, I would try to document the
side project, as in I would try to outline all of the steps for a course
a e ie f a icle hile c ea i g he ide jec . I d al c ea e
a side repo, like a vanilla repo that was going to be built for the
tutorial, and I found that was just way too much context switching
between an actual application and a tutorial application, especially
he he c de e la ch. S I ed d i g ha . I d
create a sample repo anymore, although I do keep outlining all of

263
 he e I hi k i ld ake. I hi k ha g d enough,
especially because you can go back into that live application and
start picking and choosing snippets after that.
Do you ever take breaks from writing? Are you concerned you
k ha g i g igh f idea ?
I a e g d question. Something that happened with me last
year is I took a little bit of a break from a lot of coding and writing
and making videos. That happened in line with the talks with
Digi al Ocea . I h gh ell, le ee hi h gh, le ee ha
happens here, and hang out and take it easy for a bit. What I found
i , f e a le, I ld l k a T i e . O a al da i like
h, ha e ? Wha c l? Wha g ea ? B ce I ka e
back, I started to see that not a lot changes, even though a lot is
said. React is still the same as it was, fundamentally, a few years ago,
and so is Vue. Angular has been stable for a while. I think
JavaScript has been stable, which is really cool.
S ,i ka ake a b eak beca e a l g a e al a eady
lea , i be ha ha d ge back i he g e f hi g .
I d a ha a l g a de a d he f da e al a d ee he
hif i he e he i d i g i g I hi k I l ck e gh
have been around long enough to know when fatigue sets in for a
ce ai hi g a d he a e hi g c e i , i all c cle . I hi k
f e, e , he e ha fea ha a be I ha e he
knowledge. Like GraphQL, I feel like I should know a lot more
ab , b I c fide ha , e eciall , he e a
e le i i g g d ff, i be gh lea , e eciall
i h he f da e al de bel , e all I g e I
not too worried.

264
Could you walk me through the process when a first-time author
sends you an article? How do you approach editing and polishing?
If he fi i e I ee a a icle i he he a icle i d e ha
diffe e ha if i i he gh d af age The e a l f
for creating the best article in the planning process.
In that case could you walk me through the whole process?
S e. U all a a h ld c e i , he d a , He , I
i e e ed i i i g. I d like ee ha he ce l k like. S
you know the first thing is getting to know them, because I like it
he a a h e sonality shines through. I like the quote,
The e a e i e e age , l i e e e ge [Jadah
Sell e ]. F a a h e ali hi e h gh i a big
be efi . Ge k he a h , fig e ha he e i e e ed
i , a d ha he e working on. From there it basically goes: topic
elec i a d li e c ea i , a d he e ll g back a d f h
he li e, a d af e ha , he ge he gh d af , a d he i
the overall editing process and publication.
Whe e edi i g, ha a e d i g iha a h k?
I e bee hi g e hi g f a hile I like call he ki
fac : h ell ca a eade ki a a icle? We e H Ja
Scotch, which is a tool that records your screen and shows how
users navigate through eb i e. I f beca e ll ee
them clicking though articles, where their mouse cursor moves,
he e he e ce ai f ha hi g a e. We e f d ha ce
they get to the articles, they would scroll down as fast as they could
until they saw the code block. Then they would stop, read the code
block, and then finally read the paragraph above the code block. If
he e e i e e ed, he d kee c lli g il he a a

265
image, and then same thing: scroll up above the image to see the
pa ag a h. Tha h he aj i f e le e a ead a icle .
I a , le b eak he big a ag a h , e i age i , ge
c de bl ck i he e, a d i all g ide a e h gh a a icle. I
hi k ha he e I f edi f a h . A lot of
people write long-f a ag a h , a d I d hi k i lead he
best kind of experience for readers.
Many people come to technical writing with English as a second
language or a limited background in writing, so do you think that
technical writing in this skimmable form is more accessible or
easier to get into than a more academic type of writing?
I think that technical writing is really expanded outlines, pretty
ch, a d i he a e he e eadi g c de. Y d like
code to be well documented, with a lot of sections, a lot of break-
i c de, a d I hi k ha j he e al del f
technical work. So I think that it makes sense that it transfers over
to the content side.
A he e i ha e e da ced a d a li le bit, within these
constraints of keeping the article skimmable and focused on the
code and on the project, is how do you develop a voice or a
e al le i i i g a d ake e e ill le i g ha
shine through?
Tha a g d e i , I hi k he e e fi e li e be ee
much personality and just enough personality and almost none.
Some people will use their personality and apply it to the article,
b he i ake a a f he ac al c e . The e a l f fl ff
that I remove from guest-author articles, and that just goes to
skimmability. People want a couple lines of personality and then
they want to get to the actual good parts of the technical stuff of the

266
article. Definitely try to test out how things are. When I say test out,
I mean definitely try different writing styles, push it out, see what
the community thinks and get feedback from that. Writing is such
a d a ic hi g: i a gi e a d ake be ee a d eade .
Just see what your readers like and go from there.
Y ake e ide c e , ha he diffe e ce i he
mediums in the way that you craft the content, in the way that you
approach the teaching, can you make video skimmable, etc.
Video skimmability is definitely a little more difficult than writing.
You can put timestamps in the description to let people maneuver
a d, ba icall c ea i g a able f c e f he ide . Tha
ha de d ha i i i g beca e d ha e h2 ha gi g
out all over the place.
One thing that I like to do with our guest authors is create a
TL;DR a he . I igh a , Oka , hi i he fi al C dePe ,
this is the final code, and this is our overall technique, so if you
d a g h gh he e i e hi g, he hi i he i e f
c de ha eed. Tha a he f he a icle. Tha TL;DR
( l g; did ead) i ha I like h. Af e ha , ge i
he ac al, He , a d hi f a fi i h. Le i
.
Wha I e f d he d i g ha i ha a l f g e authors
ld ki d f j d all f he c de, He e he HTML,
he e he CSS, he e he Ja aSc i . Whe e b ildi g
e hi g ha eall h i g e . Y a , Oka , I g i g
add hi a f he h l, I g i g le i i h CSS, I
g i g g back he HTML, a d I g i g g back he
CSS. I a b ci g ac be ee a b ch f la g age . Tha j
how we build things naturally. That is far harder to do in articles
than it is in video because in video you can bounce between the

267
two seamlessly; in articles you have to take your final demo app
and start cutting it apart in random places so that you can guide a
user through the process.
Tha ac all e hi g I ggle i h i a a icle: h b eak
up sample code? But chronological video makes sense.
Yeah, I ac all e j i g i a l c a ed d i g he i e
breakdown.
We e g e h gh all f c af e i , I ha e a fe ab
the business at large. Do you publish rates for freelancers at Scotch
or advertise how much you pay freelancers?
At Scotch, since we started as a smaller blog, we advertised $50
100 for a news-type article and up to $300 350 for technical
articles.
Do you think that advertising your rates helps attract people to
write for you?
I think so. One of the first things I ever saw was TouchPlus. They
were advertising that they paid $250 for an article and that was
pretty intriguing to me. I actually attribute that to one of the
e he e I h gh , I a ech ical i i g. The , I
actually wrote an article. I published it to Scotch and never went to
TouchPlus, but I think advertising the number helps.
Then again, as a programmer, with the amount of time you put
i a a icle, he a d ake i le ha he h urly rate
for doing comparably difficult freelance work. Why do you think
people do it anyway?
I i e e i g beca e e le a e d i g i de . , e le did i ,
or still do it on Medium, and they do it for free there. Writing for

268
sure makes you understand a topic better than if you had just done
a project, because to teach something in article form, in person, or
i ide , ha e k e i e e ha ha e i g
to teach, especially at conferences where questions are going to
come at yo fi e ec d af e ed e ih alk. I i a
good question. I think people like the community building aspect
of it. Our authors have used their writings on Scotch to
demonstrate their writing portfolios, and I honestly think that
technical article a e a e celle a fa f li if e i g
to go get hired somewhere.
The c i a ec i h ge f e. I d eall ha e a
question here, but do you have any comments on the community
a d ech ical i i g a d h i c e er the last few
years?
S e. I ab l el l e he e i g i g, I hi k ha eei g he
different styles of writing is pretty cool. What I think would be
interesting is if somebody went through dev.to articles or Medium
articles and looked at which ones are the most popular and
analyzed the stats. What would be the similar findings that we have
across the most popular articles? That would be a fun experiment,
especially seeing which articles Google ranks higher and why they
are that way. For Scotch, we did a lot of SEO work, and really SEO
a i h g ea c e . A he e d f he da e e j l ck ha
Google is sending us traffic. If Google changed their algorithms,
which they have a few times over the last few years, traffic could
drop and that would be e e hi g. T lidif , e a ki g ha
makes great technical content: if we could try to quantify it more by
d i g a h ge a al i f e e e ha i e , ha ld be a f
experiment.

269
Another site that is really good at content marketing right now is
aminalz [https://www.animalz.co]. If you check out their blog,
he e a ki g he e i , Wha ake c e eall g d
a ke i g? The d a l f a al i c e , hich i f .
What revenue models do you think are best for smaller,
independent sites, and which are best for larger sites?
I e ac all h gh a l ab hi ic, e eciall i he la ea
while we were being acquired by Digital Ocean. Scotch was my
project for years i bab . F e a , Al igh , le j in
Digi al Ocea a e ch a l-searching decision for me.
One of the questions that would come up, of course, is should we
ell h ld e kee g i g he e ha e e aki g? I led
me to make an analysis regarding: if you are just a blog, how do
you monetize it enough that you can take that blog and take it to
the next level, as far as income? What I landed on is a blog has one
f e : i ei he ad e i i g, hich e i cl de
sponsorships, or you find a way to create a product and then the
blog turns into a marketing vehicle.
I c ld be all g, hi i ec la i a :I j
thinking that a blog, to be successful, needs to have something that
i a ke ake eal e e e. Whe I a eal e e e, i all
just perspective. I look up to Smashing Mag and CSS Tricks. I
think they have done a fantastic job of being industry leaders for so
long. From what I understand, Smashing Mag does really well with
their conferences and that is an awesome product that they have
been working with. CSS Tricks has CodePen, which is fantastic. I
absolutely love CodePen.
If a bl g d e ha e a d c a a ke i g f a d a
earning revenue through a lot of blogs that have tried to do
advertising and sponsorship then, you see them not really able to

270
stay sustainable. You look at larger blogs like Medium and see they
try to get a whole bunch of subscriptions going, using paywalls for
a icle . If a bl g g e he ad e, I feel like i g i g be a
tough game. They say the New York Times is having trouble with
e e e, a d he e a e he la ge bl g e e alki g ab .
If alk ab i die bl g , he I ld a le defi e ha
success is, revenue wise, and then shoot for that goal. But if you are
trying to g be d ha , be e a ed a I g i g h
a b ch f ad hi hi g, I g i g f a bci i
eb i e, I eed a d c . Th e a e he h ee a I ee i . I
used to always read SitePoint, and now if you go to the websi e, i
just ads galore.
Beca e e le d ha e a d c , hei bl g a e ba icall
a ke i g he el e . The e b ildi g hei b a d, ha he
they do have something to launch, they can direct people to it. I
hi k ha h ee e le working to grow their influence by
a i g i e b k a d c ea e c e . I hi k i fa a ic. I
fun to see the pattern.
Do you have anything to add to wrap up?
We ha e ched al f eall g d ic . I g d ha
e writing this book. I think that a lot of people need that
nudge to get into technical writing.
The bigge hi g I e lea ed e hi a ea e e al ead
ched . O e i ha i ka ake a b eak beca e a l g a
e al a ead lea , i be ha ha d ge back i
the groove of things. Two, once you reach a point where your blog
ha e gh e e e a d e i g l k he e g e ,
be sure to look for an outlet or a product that you can monetize
rather than just a i g, Ok, I g i g ad be ee e e

271
 hi d a ag a h. A l f e le fall i ha a he he e
starting their blogs.

272
Peter Cooper
Peter Cooper runs Cooper Press, a publisher of email newsletters
with a combined distribution of almost half a million developers at
the time of writing. He called me from the UK to share his
expertise from two decades of technical communication.
Could you give me a brief history of Cooper Press?
We e bee g i g f ab e ea . I bega e i el my
, e ch d i g e hi g i ila ha ed i g
now, around 1998 1999. I started out doing technical writing and
freelancing for the developer news sites of the day, which obviously
were somewhat different to now. I also got into blogging when it
kicked off.
I come from that background of programming but also writing
about programming. I ran a Ruby blog called Ruby Inside that
became really popular in the mid-2000s and so I had many
contacts. I saw what was going on in the industry with email,
especially with things like Groupon. Everyone was just getting
interested in email as a way of delivering notifications, and I
h gh , Wha if I c ld d R b e , b d i ia e ail?
S e e el e i g i g d hi , le d i fi .
I began this weekly publication called Ruby Weekly, which is still
going, and it went from there. When I began, I had a few thousand
people sign up really quickly and a lot of other things had a
domino effect after, like the whole Mark Zuckerberg strategy he
targeted Harvard and then he moved on. People at Harvard had
friends at MIT, and MIT people have friends at Stanford, so he
would go from school to school. Likewise, I went topic to topic. I
went from Ruby to JavaScript. I do frontend stuff, and it all grew.

273
Whatever topic I thought the audience wanted, they got a weekly
newsletter on it.
Tha e ch he e e e a da . I bega i all j
e li e c e i R b i i iall , b I d d
courses in JavaScript or many of these othe ic beca e I
the expert of every topic. I took on sponsors to justify working on
he e le e , a d ha e ch he c e f ha
b i e i . We e d e he hi g a i e ha g e b , b i
terms of what Cooper Press actually is over the last seven or eight
years in particular i ba icall elli g hi e le a d
running the newsletters.
In your estimation, what makes a good technical article?
Something that makes a bad technical article is something that is
extremel ale . I d i d if a a icle ead , He e a c l
hi g ab h e e ice. B he i e hi g ha
ki d f hidde like, U e e ice beca e i d e , , a d ,
a d he d eall g i de h ab ha he ble is, I
think a lack of detail and trying to be too salesy is what ruins an
article for me immediately.
Wha ake a a icle g d, h e e , i he i d e ake
long to get to the point. I want to know, at least above the fold,
what is this about. You might think this is really obvious you can
tell from the title what something is about b ha eall i he
case. I come across so many articles where the title is abstract or
d e ake a e e.
L ki g a e hi g like a icle , f e a le. Y e
i e ic like H e d SMS Me age i h AWS
La bda. O i ha ld be i e i le, b e
acked he SNS a d he P h 3, ei edia el ade

274
it more relevant t a alle g f e le. B i highl
relevant to them.
Tha he i not only can I tell what your article is about,
b e a ge ed i a bi . Y did j i e He e h
e d SMS Me age , e ac all g e dee d a d focused
it on someone. While you may have excluded some people by
d i g ha , I hi k ha a ge i g ac all be efi a l a d ha
certainly true when we add links in the different newsletters.
I al a l ki g f he ge e ic hi g ab h w to
l ea ble ; I l ki g f h l ea e ecific
ble f a e ecific g f e le. I d al like f
anyone to be able to read it and gain some insight into the general
problem.
That brings me to a third point, which is that domain-specific
knowledge is very, very useful in writing. Anyone can go and learn
a ech l g a d a , Al igh , he e h ie fi
g a i P h , b ha e eal backg d i i . H e e , if
someone is an astrophysicist or a biochemist or a marketing growth
e e a d he lea h e P h , i bec e , H
write your own thing in Python that is relevant to being an
a h ici . Tha ag ifie he i i g al e b a h d ed-
fold, not merely by being more specific in the topic but also being
specific in the problem space. There is domain-specific knowledge
that you know is going to go into an article like that. The writer is
going to write from the perspective of, say, a biochemist and
he e e e fe e le d i g ha , o it adds a ton of value straight
away.
Wha a e e e d e b e ed i ech ical i i g? Wha
would you like to see continue, and what do you hope dies out?

275
O e hi g e e ee i he la fe ea i a ic la i he
repurposing of content ac diffe e edia. Tha iea
common thing to do now. You might end up with someone doing
a podcast interview with someone where they might take a video
recording and release that as well, or they might post on social
media and clip out quotes. I thi k ge e all ha a g d a g ,
a ic la l he i al ide. I d e ece a il hel he
end audience, but it helps to increase the size of your audience. I
hi k e ll ee a l e f ha g i g , a d I hi k ha a g d
development in recent years.
You used to write an article, put it up, and bam move on to the
e e. A he hi g I e ee a bi e e he la c le f
ea i ef e hi g c e . Agai , hi did eall e d ha e
in the old days, but now people are finding their old blog posts
from five to ten years ago. For example, the post I mentioned of
, Se di g SMS e age i h AWS La bda. A e
point AWS Lambda is going to change in some significant way and
e e g i g be hi ki g ab P h 3a e, e e
going to be thinking about Python 5. And maybe instead of AWS,
e ll be hi ki g ab a diffe e la f f e e le , a d
on. If you went back to that article then and you went through it,
ld hi k, Well hi all akes sense but I need to change
the technical parts, and I need to update the code examples and
the screenshots and things like that, and then I can republish it as a
e hi g. We e eei g a l e f ha g i g ece l ,
which I think is a good thing as well.
A perennial issue is focusing on titles. We did see a trend three to
four years ago back where people were trying to be very clickbaity
with titles. There were all kinds of publishing companies and sites
that would take feel-good stories from the media and write these
eall l g i le f he ih a d belie e ha

276
ha e ed e ! F e a le, S e e f d e c e ki e i
a bag a d belie e ha ha e ed e . The ld
that up, but it would just be a video like a YouTube embed or
something and all they were doing was siphoning all of the traffic
with these clickbaity headlines for things. This was a business
del fi e e ea ag , b I hi k e e ee ha ei ed i a
little bit in the last few years, particularly in the technical space.
Pe le a e bec i g i e i , a d he e bec i g fa ig ed, i
the same way they became fatigued by banner ads and things like
that. People are just getting tired of it.
We e eei g a e ic a ach i he e se that people
a eg i gf e clea de ig . The e cali g back he ad ie
a lot. People are even producing completely static blogs, just using
HTML a d CSS a he a le el. We e eei g a l e f ha
especially with developers. People are fatigued of all of these bells
a d hi le a d ig a d hi , ha , a d he he , a d e e
moving back to a simpler age for a lot of content. There are still
publishing companies that have banner ads everywhere, but they
ee be he a e. I e een a few closed down over the past
couple years. It seems like that stuff on your site is a sign of rigor
mortis in publishing at the moment. Publishers need to find a way
f e i i g ha i a li le e ble, le a .
The final point to make on this is that we are seeing people
experiment with different types of monetization, different ways of
ha dli g ad e i i g, he he i ia hi i g
YouTube. Going after the YouTube dollar has a lot of controversy
itself. Publishers are doing signups, so things like Substack a
company doing a lot of promotion around paid email newsletters.
Tha i e hi g ha e d , b he did a ach alk
about it because we have a lot of newsletters in the space. People
are paying three or four dollars a month to receive these very

277
 a ge ed iche e ail a d a a e l he e d i g i e ell. I ee
them popping up in the media space. If you get a thousand people
a i gf fi e d lla a h, e e ch g a j b
there. I think e e g i g ee e cha ge i h hi g a e
f ded, ece a il b b c i i , ha j a e a le.
We e g i g ee a a ie f diffe e hi g ha e i g a d
sponsorship or even companies paying to have you on as a writer
and producing as a publisher and keeping you employed.
As a writer, how can I write content marketing pieces so that
he e legi i a el ef l eade ?
I e e e eall bee i ii ega di g c ea i g ha , I
can only speak about it from the perspec i e f e e h
eadi g hi ff. I d k if e fa ilia i h he k f
Kathy Sierra, a great example to research and look up. Kathy has
been related to the developer content space for 20 30 years, a
ridiculous amount of time, and she has a lot of respect. She has this
whole thing that she promotes: your goal as a marketer, a
de el e , a i e i ake e feel Kick-A . Y
goal is literally to make the users of your product, in this case the
users of the SaaS product ha e e i i e i g, feel
like he e be e e le. H ca ake he l k g d i
front of their boss?
I hi k ha he e eed c e i a iece f c e . Y
are writing this piece for someone who may be a customer of the
company already or they may not be a customer and they need to
ig .Y e i g b ild he c a a die ce. The
question is how can you get the reader into a position where they
ca l k g d he ca feel g d ab ha he e d i g?
That d e ece a il g d he li e f Oh, e e g hi
g ea hi g, c e a d e i , c e a d e i . I e like,

278
 He e h ca achie e ei e e i g ele a hi g
d ih j b, He e h ca ake e f he k
off of your plate, how can we make something easier in your life
i g X, Y, a d Z a d Z j ha e be hi g. A l g a
the writer is transparent about that, people are okay with it.
A company like Twilio is probably a good example of doing this.
I e defi i el ee ial f he h i g h c ea e
something that hooks together certain services and notifies me via
a SMS he a e e g e d . The he ll i e a ial
about that and obviously it will use Twilio for the SMS part
beca e he e e ch he l ga e i f d i g ha a
cale. S ill, he ll e lai h d ha a d c ld i g i
a he e ice. Tha he c l hi g ab he ial you could
put another service in its place, but people read the tutorials and
hi k, Oh I ll ac all ig f T ili a d gi e hi a g a d
e d SMS. Th e a e he e fec e f ial showing
someone how to achieve a certain end and the end involves the
product but the end is not the product itself.
Do you mostly curate or commission content for your newsletter
and why?
We c i i a li le bi he e a d he e. I e hi g e e
had a huge amount of success with. Given our internal processes
actually, keeping on top of it is difficult. If we could sa , Oh, eah,
g a d i e X, Y, a d Z a d e ll l k a he d af a d k i
f he e, ha e hi g, b a k al f i e eed
a bit of chasing and following up with deadlines and stuff like that.
I b d i g he e le e s and other people in the
company are busy doing other things, so we would need a better
process to do that at scale. We do it from time to time with people

279
who we really trust and we get on with, but in terms of doing it at
scale no we do not. We are pretty much 95 percent curating.
Why commission content for your newsletters?
Getting other perspectives and fresh faces to be involved in things
i be eficial. Y ca d e e hi g elf. Ul i a el i ab
cali g, a d I ad i ha e hi g e e ki d f failed i h.
We e d e e ell i h c a i , b i e f
c i i i g, ell. I e hi g I d like e l e i he
near future.
What is your process for finding and sharing good articles with
your readers?
The e e different ways that we do this. The first and most basic
way is that the curators who I work with and I are familiar with the
top blogs and the better sources of news for certain areas, and we
g h e a d e kee a e e he . I a i le a ha . I
like i h Dja g f e a le. Y e babl g i g k
what the most interesting Django sites are and who the people are
in the scene. You keep on top of that i ea ea . The e
level is social bookmarking and social sites. There are people on
Twitter who always like the right stuff or retweet the right stuff or
sites like Hacker News or Reddit he e e l f i ila ki d f
places, including tech sites like lobste.rs for example. There are a
ton of sites that you can keep an eye on in each field and obviously
b eddi a e ef l f ha a ell. We e j l ki g a
stories but also going into the comments because a lot of stuff gets
faced he e ha e le d ice if j ick he f
age f hi g . The e a l f eadi g d , b ha a he a
of finding content.

280
Thi dl , e a a a e li le bi f hi . The e e ce ai
Twitter searches you can do and certain sites and certain feeds you
can look at things like that which you can automatically crawl.
Then we turn them into these pages of information that might be
relevant this week for the newsletter. We can go through that
a all a d a , Tha g d, ha bad, ha e e , a d i e
the things that we like from the list. This catches things that we may
have missed by searching manually.
We also have some tools and this is relevant for code in
particular some systems that can go to GitHub and do certain
searches through their API. They will find all of the JavaScript
projects within the last two weeks that have had a release, for
example, made through GitHub. So we can see, for example, that
version 2 of something came out or version 1 of this came out,
ha e e . Tha ac all gi e al f c , if ha he igh
word. Reddit a d Hacke Ne ece a il ice ha
e i 1.0 f e hi g ca e if i like a id-level library.
Pe le j a e a i g ha a fa e i .B e ll ee i
e ll be able b eak he , Ve i 1 f hi c l lib a
has c e , hel ei,a d . We d ge i e a fe
scoops like that.
Another way is that people reach out to us. I would say about a
third of our links come from other people who are readers or who
run these projects and they know about us. They send us a thing to
a , We e elea ed -and- e e be e he ll a , We e
about to release so-and- , d a iei ? S ei e
we coordinate with people so we can reach them a little more
di ec l . If i a eall g d elea e, for example, and in return we
get the story.
As a medium, what benefits does email provide over blogging?

281
For me, it is about the format. With an email, if you put a schedule
i a d a i eekl hl , i a bi e like i i g a
article beca e e g a deadli e a d ha e ee ha
deadline. Whereas with a blog nowadays there tends to be this idea
that I need to have a certain amount go up and I need to keep
posting, which is just a different type of stress.
Wi h e ail, f e, i s the engagement that really sells me on it.
Tha ha g e i i iall i h i : I c ld e d a e ail 1,000
people and then I could see that 500 of them clicked on a site that
e li k ha e i e. Wi h a bl g, if eg a h a d
subscribers, it is more blithe. People will click on stuff but people
igh ead i a eek la e a ea la e a d j d ha e
engagement in the same way that you do with email. Email
c a d highe CPM a d beca e ge ha e gage e , i
as simple as that.
You can test out a concept and see where things are going. You can
succeed or fail more quickly than you could if you were beginning
a publication or a magazine or a blog, so you can double down on
topics. For more information, see: Article: New media companies
h ld a i h a e le e . Thi g hi ki g i he a e a
mine.
How do you find advertisers and sponsors, and how do you grow
and develop those relationships?
I only dealt with this really early on. This is actually one of the
aspects about growing and taking on staff I e a aged ge id
f all f he hi g ha I e g da ha c e
much time. Advertising is one of those areas. Very early on, as I
said, I built the company to promote my own courses and that
worked quite well. As I scaled up and got sponsors, they literally
reached out. Their employees were reading the newsletters and

282
 he e e f a di g he hei a ke i g de a e . Tha
actually very common. We will get leads because a developer has
read our newsletter and forwarded it to the marketing department
a d he a ke i g de a e ge i ch i h a d a , Ca
e ? We e hea d f e gi ee ha hi i a g ea
e le e . Tha i e e ce fh e le fi d our
readers recommending us to their marketing people. They would
each , e d eg ia e. O e i e I ke a e e ha he
people in the email space were doing, not necessarily developers
but other niches where they tend to have a PDF with a media kit.
Then we send that across the marketing departments and go from
there.
We d d a b d we just respond to inbound requests.
Tha i e a i ilege f .N al fc a ie ca eall
i e i ha a , b i ee ed k f us. Once I started
hiring people, I hired someone who was proficient in sales,
e e ie ced i h ale , a d he ake e he h le hi g. N
he ha e le h k i h he a d i k eall ell. I bee
such a simple process on the business side f hi g . I e gi e
a a he ea ble , a d I e g he ha d ble f cali g
he edi ial a d hi g like ha . I e a l gi ic i e ha a
issue of finding people just because of our readership and the sort
f e le he a e. I ite happy with that.
How do you hire as a small company with a global reach in a
remote area?
I think we have been very lucky in that regard. There are seven of
us although one is my wife so there are the two of us and five
employees. I found one of my employees through going to the
local meetups related to technology and the others have come via
al j b ad ha e e Faceb k lace like ha . We

283
have two towns that are somewhat bigger, about half an hour away,
ha bee ef l. I like e e c le el i ac e
of nowhere e e ela i el e eb e e e. We e
remote by English standards, which means by American standards
e li e i he b b . I diffic l fi d e le, b e
do work predominantly locally.
We have curators around the world who work on a freelance basis.
They work for other bigger companies and do this on the side. We
a he i ha a , b ed ha e a f ll-time remote
e le. I d i e like e l e i , b e e e e g tten around
to actually doing it. The main issue with hiring in a place like where
I am is that it is possible to find people who are good writers or
who are good at sales or people that have general internet savvy,
b i e ha d fi d e le h a e ech ical. The e i ha
ki d f ka d he e. A e h a eall g d de el e ,
f e a le, ld li e he e. I d be like i g fi d a eall
good developer living in the farthest-flung corner of Iowa, for
example. There would be the occasional person there, but the
basket from which to hire is very very small compared to Chicago
or wherever.
We could have problems in that regard. Luckily I am the most
ech ical e he e e e h gh I he c a ,I he
one in charge of handling any development that we have to do or
building internal tooling. That works quite well for me because I
like ga i g a d I ha d i . I d a he hi e e le
ha dle he e ba al i babl he dI ld e, babl
not in front of them, but the word I can use here the more banal
tasks. These are the things that either I can do but I just find deadly
boring or things that are perhaps are a little more of a struggle for
me like the sales side of things like calling people up on the phone.

284
I he e a hi g el e d like ge he ec d?
Righ ,a ac a , e e hi ki g ab h e e bee
doing this for ten years. The growth is kind of so-so. It used to be a
bi highe , b e e ill g i g. I a ca e f di c e ing the next
niche or the next format. Email bubbled up, but what should we be
d i g e ?S ei e I if e e bli d ha c i g
a d he c e . I e bee kee i g e e Y T be a d
podcasting, things that do not necessarily fit into what we do. The
d ci i e e i high f . I g e he e a l f
uncertainty around this area right now. While software
development continues to be a burgeoning scene so our topic area
i g d, h ca e e ai ele a i hi ha ? Tha omething
ha e e ill ki g a d hi ki g ab . Whe e i hi all
g i g g a d ha a e e g i g be d i g i e ea i e?
To be fair I think most people running most businesses have that
ki d f h gh . I e ce Vogue magazine had been going for
e ea he e e a ki g, A e e le ill g i g be b i g
aga i e i e ea i e? A h d ed ea la e , he e e a e.
Ma be I d l hi ki g ab he e ki d f ic , b i a
good sign of what it is to be in publishing. P bli hi g i j
ab a i f i g da eade a d d i g ha a i fie da
a ke , i al ab a ici a i g ha a i fie
market. Our goal is not to keep a certain number of people paying
us five dollars a month; our goal is to continue to reach new
eade . Tha ac all a be efi f a ad e i i g-based company
like us while we sell advertising to sponsors, we really have to
think all the time about how we remain relevant to readers.
Without the readers, we have no sponsors. These are interesting
i e a d I hi k e e g i g ee l fi e e i g
de el e hi decade. I j i g fig e a he
moment exactly what they will be.

285
286
Angel Guarisma
At the time of our interview, Angel was the Director of Content at
Linode, a cloud computing company with a major presence in the
open source community. He now works as the Director of Product
Education at Humio. At Linode, he led an in-house team of
technical writers and editors and worked with numerous
freelancers to publish wide-ranging and comprehensive tutorials
and documentation. He began the call by giving his take on the
state of the industry.
[Unprompted]
S e hi g ha I e al a h gh i ha he e hi di c ec i
the world of technical writing between what we do as in you, the
e le h e i e ie i g and technical writing as a field
e he la e ea . The e hi diffe e ce be ee ii g
camera manuals and airplane-part manufacturing manuals and
writing API documentation and how-to guides and tutorials for
de el e . Thi i bei g ec g i ed , b he e a h ge lack
of allow me to maybe make what we do sound a little more
important he e a h ge lack f ca ical li e a e i be
practices, things people should be doing, things people are doing.
Tha h he he b k Docs as Code came out, I was
pleasantly surprised. My team had adopted a docs as code model
as of two years before the book came out. I was preaching this
model, saying we should do this, and I was hearing about it from
other people that lead technical documentation teams. But people
aid, Wh d c a c de he c ld ha e a CMS a d all f
he e he hi g ? C i g f a de el e backg d
myself, I understand why you want docs as code. The idea of
convincing a manager, your peers, people in your company, even
e le h e i e ie i g ha he e c i g d hi j b

287
a di g i g be i a CMS I ab c ica i g he
why of that.
I hi k i c l ha e i i g hi [b k] because this field
is in a stage where things are changing very quickly and people
ae alki g each he e gh. A l f ff ha g i g i
c ica ed b d f h l ki g a he e le
Gi H b e i ie ee h he e implemented
d c e ai .I eg e f a i le e e f he
things that my team has done in open source documentation, for
he c a ie ha I d a a e, beca e e f ha
e e d i g, i ab d ha he e le d ha e it.
Thi i f a a ide, a d I d ea g ff a hi , b
all f hi a : ha e d i g i eall i a a d I hi k
that the field of writing tutorials and documentation about software
truly needs this.
Tha k ! Le di e i : hat is your process of researching,
writing, and editing technical documentation, more specifically
tutorials?
We do everything open source, just for the record, so I can pretty
much share everything down to the nitty-gritty, because you can just
check out our GitHub repository and see it all for yourself. At
Li de e e al a bee f c ed he a he ici a d he
helpfulness of the guide and of the tutorial. To do that you have to
e dal f i e e ea chi g. Le a ed c e i g
Kubernetes or something really complex. You can only write about
ha f a i f a h i if e ed i , i i i .
A e ca i e ab K be e e , b if e ed i a d
understand the pain points of it, then you can write about it from a
point of authority such that a developer will look at a tutorial and

288
 a , Tha k , hi ac all l e e f i e, gi e e
a c ce al de a di g f h I ca l e i e.
S e i e e ake he h le ea a d e ll e ea ch e bject
ge he . I eall i -de h e ea ch, h gh a he a e i e e ll
manage updating our library and some of the miscellaneous tasks
that come in from the open-source community. My team will all go
down different paths of a topic to start researching. Everybody pulls
d he hi g a d a b ildi g a lica i if i a la f ; if
i a ga i g la g age he a ki g i h i . We ead
he ial , e ead he d c e i i gd c e ai ,a d
we have sit-downs with each other where we do knowledge
a fe like, Oh, he , I lea ed hi . Did k hi k
ha a ? We ha e i e ha e e e ha i g al g he a
and we try to solve them. What we create is an internal knowledge
base of documentation and links about he hi g ha e e
researching.
Whe e e ac all ii g ial , e ca f lea back
all of that effort that we made in the research portion of this
process. When we actually write, we not only have a better
understanding than when we started, we also have a team of people
who understand this topic and are currently writing about the same
hi g. We al ha e a i e al k ledge ba e he ic. Le
a ha ha e a i e hile e aki g a ial e
sort of software. If el ha e a k ledge ba e lea
back he e e e hi g f c a ed a d ha e a ea
help you troubleshoot. You end up learning more about the
subject ha ceili g f k ledge ha e c ea ed i e agai
because then everyone starts to learn more.
O ce e feel like e e l c f able if i a e -source
project we try to talk to the maintainers we try to look at the repo,

289
we join slack channels, and we see what kind of stuff is going on.
We also talk to our internal engineers just to see where they are.
We h he e f e ea ch a d e if ha e e he
igh ack a d he e ca a i i g. I d k if k e
this, but my internal team here at Linode is actually really big, and
the freelancing team is bigger than that, so we have the resources to
really spend time researching.
Out of the research phase we devise topics. We realize that there
are these gaps that need to be filled in existing documentation.
There are common occurrences that people are finding and asking
for help on, in product-specific Slacks, on Twitter, and in random
places people are having these issues. Out of that we emerge with
ha he ial i le ill be. The , e e i e g e ff a d
begins the writing process.
The writing process takes anywhere from about a week to three
weeks depending on how tough the concept is. After the writing
process, we do a technical edit. The technical editing process is the
point in which all of the writers have the opportunity to, without
consequence, question every decision that was made in the writing
ce . If eb d i alled e hi g i g, I d k ,a
private repository maybe they added a custom repository or they
installed a random library in that moment the person performing
he ech ical edi ge e i ha a d a k, I hi eall he
igh a d hi ? I hi eall he hel f l a d hi ?
S e i e he e ii g eall ca e ab he ff ha
hi k i c l, a d c l i ece arily helpful to the audience
that consumes this documentation, and so the coolness of it gets
questioned. Then we are able to either accept something because
somebody did make all of the right decision and then that person
can become stronger in their convictions in their creative decisions

290
(creative used liberally here because it is technical) or we can catch
mistakes in the process.
Af e ha e ha e a c edi i g ha e, a d c edi i g ha e i
e ac l ha i d like. I l li e edi i g and grammar;
i al a ki g if hi i f a i i e e ed i he be a
possible. We also have this automated step that happens at the end
where we check for style and spelling and grammar at the
c i i eg a i le el. We e b il a l f e ts, which help
ca ff a iece. Af e all f ha d e, e ha e a e ie age
where one person who has not been involved in the writing of this
piece, the editing of this piece, or the technical review of this piece
reads the piece from top to bottom without actually trying out the
steps (that was done in another stage). They review it and if it meets
the standard of a piece of documentation for us, then we hit the
merge button in the pull request and it goes live at our release
cadence.
Within this process, you seem to have a really strong preference
for making the highest-quality piece of writing that you can. What
do you think makes an article good?
I he a he ici . A b d ca g ie H I all Kafka
Ub . B , he e i a a d it that is genuinely helpful to
a e h i ac all a ki g ha e i . I e hea d f he
de el e a die ce a d I e hea d f eade ha he
prefer us when we go deeper and we tackle really really in-depth
subjects like programming or Kubernetes with a really analytical
le . A he a e i e e e hea d f a hi i h d ed
thousands of people in my time here at Linode who really like
those simple and easy guides. Easy conceptually, easy technically,
hi g ha e e le d even have to think about anymore.

291
The eall like he beca e he e he i a d he a e
the question.
It all comes down to this authenticity piece that I really, really try to
hi h e he I hi i g a d b ildi g ea . I d e a e
ha e i i g ab , i hi ea , a l g a i i hi
space, but the piece that really separates what I think is quality
documentation from what I think is documentation that people
ha e i e i hi a he ici iece. Tha ha e do that in-
depth research for. To write good tutorials you have to be able to
elf i he h e f e le h eed he . S if i hel
ial , if i f hi g ha a e b ke h e e hi g
up, you have to put yourself there. You really have to try it from
that perspective, even if that means blocking off some of your
existing knowledge and approaching this as if you were the person
h e ii gf .
At Linode our customer support team hires people from all kinds
of walks of life. We get people who are extremely technical from
the get-go and we get people who have in-depth knowledge of
security. We also get people who have customer support
experience in some other field. When we write technical support
documentation, my team of writers and I look at them, literally,
because we sit across the building from them. We look at them
a d e a k he , D e hi add e he i e f ?
This authenticity piece means writing stuff that is genuinely helpful
ha alle ia e eb d i e. Tha hel eb d lea
something new and gives them the confidence to continue moving
forward. If you have this really hard topic, you first want to make
sure that somebody who has only ever heard the word can quickly
get up to speed on what it is. Then you write something to answer
he e i , Ok, k ha i i , h d i all i ? Ok

292
 e i alled i , h d e i , e ligh l ? Whe e
used it, how do you build something kind of complex on it to
lidif hi h le c e f lea i g ha ed ake
lace? T d all f ha , a e e age f he j e fa ic
a piece of technical documentation, it has to be authentic. The
writers have to have essentially lived through it.
I hi k he e a li he e i he ld f ech ical d c e a i :
there are a lot of technical writers who are excellent writers, but
he e eall ech ical, he e ligh -technical, and they need
a lot of engineer interaction to produce technical documentation
ha eall g d. Tha fi e ha h i k f al f
people. In my opinion when that writer takes the step moving
forward and goes through the motions themselves, then and only
he ca he ief a e ec i e f e e ie ce a d ha
ha ake i l , l e e la d c e a i . I j e
ha d i g hi , b he a , he e e a l fc a ie igh
in the space that have exempla d c e a i . Whe I e alked
he , ell a be he d call i a he ici , b he ai
their writers in this way.
The e hi h le he iece a d a i g alle ia e he l ad
. Ma be i f c e -support team or your engineering
team. The best way to do that is to have a writer who is living that
ff da da . Tha a ha e e h ech ical
ca i e g d ech ical d c e a i . I a i g ha e e
who is technical can write authentic documentation more
efficiently.
Beyond authenticity, do you have any other discrete tips?
S e, i ha I ha e f i e a d edi . The bigge i
i Th ee i !

293
Be ech ical. Y d ha e be a f a e e gi ee k
how to write code, write scripts, read code, look at code, and be
able edi i . Y d eed be a e e gi ee be able
to host your own infrastructure, have a database, and build out
all agi g e f elf. Y d ha e be a da a
scientist to try out some machine learning algorithms. But, that
ability to try these things and wrap your head around them and
ead he d c e a i ha i e f he i a
hundred times better place to write documentation. Some of the
be d c e a i I e ever read is written by people who are not
d c e ai i e . Wh ? I beca e he e li i g ha ff
day to day. If a writer can invoke that in the same way that a fiction
i e igh a el a ci ha he e i i g a b k ab , j
sort of understand it if e g i g be a ech ical i e i hi
world, you need to eat sleep and breathe this world. Sure you can
read Hacker News, but every time those Show HN things pop up,
try the project out.
My next tip and this is also really good for people who are trying
to get in this space is contribute to open source. The amount of
jec ha eed d c e a i igh i h ge a d if e
one of the people who is willing to teach users and hold their
ha d , ell if e illi g d ha , i a i e. A a icle i
Linux Weekly news came out this week on contributing to
d c e a i i he Li ke el. Tha e e el hel f l,
right?! By writing that, you learn to interface with people at this
different layer of abstraction tha e babl ed ki g
i . Whe deal i h i e all da , e ed alki g
writers all day. If your technical writing team is part of your
c e a ke i g ea , e ed
interfacing with engineers all day, but you still need to. The open
source projects are a critical way for you to get feedback and
e e ie ce d c e i g. Whe I a d c e i g, b he a ,

294
I ill alki g ab i i g h - g ide a d ial . The e
such a need for that. For example, join the special interest group
for Kubernetes documentation writing. Come write for any of the
companies that are probably being interviewed for this book. I
hi k ha eall big.
The third tip is version control. All writers should be pretty
proficient in using Git, and a lot of people think that learning how
to commit something and push it up to the master branch is
e gh. Tha h I ha i g hi e ce hi g. Whe
you contribute docs to open source, you can make these mistakes
and people will help you through it. You will in turn learn how to
use version control, or Git specifically. That, while not directly
related to technical writing, is what I think the whole field is moving
igh . B bei g eall g d a Gi , e able to contribute
jec . Y e able hel f e le a d bec e e
ech ical elf. B d i g ha ei e ech ical a d
can write better how-to guides and tutorials.
Y e gi e e g ea i f ai f a ie i g echnical,
what about technical person who wants to be a writer? What do
you tell the person who lives authentic engineering in daily work
b d e ha e c fide ce i h i i g?
I believe engineers just need to try writing and reading
documentation. We do things where we watch engineers read our
d c e ca de a d h he e c i g i . I hi k
sometimes they just skip to the code block, put it into the editor,
try to run it, and if it breaks they go back and they do this back and
forth thing. But, if an engineer puts themselves in the shoes of a
c e i he a die ce ha g i g be i g he d c,I
actually think that naturally the documentation piece will come out.
Ma be i be g a a icall c ec . If g a a i he

295
strong suit, or style, for that you could use Vale, which is this really
cool linter for natural language. You can use all kinds of tools that
help that.
I really believe that the technical aptitude and the element of
reminding yourself that humans read this are more important than
he k ledge f he E gli h la g age. I ea ie e gi ee
into technical writers than it is to turn somebody from not in the
ace i a ech ical i e . I ca be d e, a d I e d e i . I
want to be clear: it can be done, but you have to seriously love this
stuff. I have a really diverse team made up of people who have
backgrounds ranging from poetry to anthropology all kinds of
hi g . Beca e f he a ha I e b il he b a di g ce
and the way that we do things, our people get really good, really
fa . I he i he e e a d i f a c e, e
write our own tests, we do everything ourselves. There are people
here who have never worked in tech before who are able to write
tests and do this stuff, and they learned it not from a bootcamp but
from being a technical writer on this team.
How do you keep the content and archives up to date with
changing technology? For example, what if you have a bunch of
Python 2 tutorials and then Python 2 gets deprecated?
Tha a eall g d e i . We ha e a big lib a ha e el
a lot. The Python 2 thing is a little different because everyone had
this giant heads up. With a library as large as the one that we have,
a dI e he e le ha e, e el n our open-source
community to flag things that need to be updated for us. Or,
because our library is open-source, community members might just
ake he da e he el e a d e ll e ie i . We al ha e
somebody on staff who is dedicated to updating things one person
on the team who basically takes feedback from the community in

296
the form of comments, GitHub issues, etc., and updates
documentation accordingly. When a new version comes out of
e hi g, e e able ge i a fa a ible. I a ixture of
having a person who updates as their job and also relying on the
community to help us. We have a really good community
e e ce, ha ha e e f e . Al , he i big hi g
like Python 2 to Python 3, or a big distribution change, then we get
notified ahead of time that those are out and we do sprints to make
sure we update those as they arrive.
What makes it a worthwhile investment to hire someone who
keeps the capacity in your team to update old information versus
constantly focusing on churning out new technical guides?
Whe e e a i e a a iece f d c e a i , i i a
ha e ac all e di g he ff he g ack. E e
if you write it really well, people still just skim down to the thing
that the eed, he c ld i ha ha he e l ki g a i
about the right version or something. We put deprecated
notifications on guides, and we do this very purposefully because
sometimes people use legacy systems and they need a Debian 5
version of a iece f d c e a i beca e ha ha he e
using. But, somebody will arrive there and miss the giant banner
ha ead , D l k a hi g ide if e i g Debia 5,
D l k a hi g ide if e i g P h 3. The ll ge
i f a i a d he ll h hei e . The ea ha e
update the guides is so that at least we can say that we made as
much of an effort as we possibly can to make sure people are being
helped.
The reason that we write documentation here at Linode is to be
genuinely helpful and to inspire confidence in people. We have to
make that investment to hit both of those things ca be

297
ge i el hel f l if e da i g d c e ai a d
ca i i e c fide ce if eb d b eak hei system after
following your advice.
You still keep both versions, right?
Yes. We rarely delete versions because of the edge case where
people use legacy systems and come to those old versions directly.
Le alk ab ki g i h f eela ce i e . Wha are things
that freelancers do that are really helpful?
We work with a lot of freelancers. We have somebody on this
team who is exclusively dedicated to interfacing with freelancers all
of the time and editing their work. We have written a rubric for
acceptance, instructions on how to submit a guide, instructions on
how to use Git, and instructions on all of our tooling so that
somebody can render a document according to our guidelines.
What makes a writer good to work with: someone who wants to
have a long-term freelance relationship with Linode and somebody
h eall ake he i e de a d h e e d i g i a d h
e e d i g i . The e hi g e ha ha i g eb d ig
ha he e ead all f he e d c e a d he ge i g a iece
written in Microsoft Word.
Part of why our freelance program here at Linode exists is to give
technical writers a platform to explore their ideas within the context
f ha e d . We e a cl d c i g ide . The c i ical
aspect there in a freelancer pitch is that I know that they want a
long- e ela i hi . Tha i eb d I a k i h. I
be e ha e le h b i ii g a d he a , He , I
just wrote this doc for your competitor I can change a couple of
words and you guys can ha e i f hi ice. We ejec ha ff.

298
What makes a freelancer good to work with for us is a willingness
to take feedback. We dedicate one writer to a freelance project
who goes line-by-line on something submitted so that the freelancer
can submit a better submission. The idea is that we create a better
long-term relationship that way, and so even we still get writers
where we ask for revisions and they say no or they ghost us.
A he hi g ha big i ha if e i i g ab ga i g
or wha e e ic e i i g ab , ha e k i . We ge
al f ial he e he c de d e k i i e eall
poorly, and sometimes I believe that people try to slip that under
the radar. But our technical team of technical writers can read the
code. We will say this is wrong and that puts the writer in a bad
situation. We want to work with you, but you have to fix this, and
e e a ed e i e. We a a ,b if d
try. I find that good freelance talent in this space is really, really
hard to come by, so relationship that the freelancer builds with the
editor is crucial.
A lot of our long-time freelance contributors are actually full-time
e gi ee . The e hi idea ha e e e gi ee ha a lea e
good guide i he . We e c age he e e if he d feel
confident about their writing. We have editors here, so the thing
ha e e a i g f , he hi g ha e a e hibi , i he
e gi ee k ledge f a bjec . E eciall a d he h lida ,
we get a lot of engineers who want to contribute like this. If
everyone has one guide in them, how can you, as a place that
sources freelancers, encourage people to do that? One thing that I
do is read a lot of blogs, specifically on programming, and I reach
o al f h e i e a d I a k, He , hi i eall g d. D
a ief ? I al a e i d he ha he ha e
e hi g i he el e he ld ha e i e hi bl g
tweet or project on Hacker News.

299
Do you have any other comments on overall content strategy and
relating the content that you make to the products that Linode
provides?
We always write about the products that we make as a company in
this space. We try to release the products that our customers need
and deliver on that. That means that around the product-agnostic
content that we write, we always also have to write this product-
ecific ff beca e i eall hel f l. I hel f l c e
base to know that we have solutions that could be alternatives to
d c ha he e i g.
Our content strategy themes last several months. Maybe a theme is
configuration management, and so for the longest period of time
e e g i g be i i g ab c fig a i a age e . The a
product releases. We know ahead of time so we pepper these
sprints (we work in agile) with those products and we sort of ebb
and flow or change the ratio of themed posts to product posts
according to how close we are to a release. When we have new
products close to release, we have technical writers doing meetings
to really understand what the products are and ask questions so
ha e k he i k i e d c e a i a d ha
documentation we should be writing. The product-focused stuff is
always something that we agree on as a company needs to come
out. Then we change the ratio of kinds of content themed
content to accommodate that.
I he e a hi g el e d like add?
I ca e dee l ab ech ical i i g a d I e e a l f i e
obsessing over documentation. Not just our own. I read
documentation for fun sometimes. I think that a lot of people are
doing really really really great things in this space, but there are still
al f k .Id hi k ha e le like e ha

300
documentation teams talk enough with each other. I really hope
that we can share our insight like I gi i g , f hi b k
with each other so that we can make this field better and be taken
more seriously. There are still places, and you read about it on the
Write the Docs Slack all of the time, that employ one technical
writer who is responsible for web development, Twitter, and all of
these other things. These writers are absolutely miserable.
You build a technical writing team because you have an
e gi ee i g ea a i g, We eed documentation. People need
to know how to use these projects, and we need to know how to
b ild a d c e a i ea . Pe le g igh a a a d l k
how Google built a documentation team or how Amazon built a
documentation team, and they end up not building the
documentation team that is right for them. So, you have these
documentarians who are really good at writing tutorials on code,
h a e eei g j b de c i i ha l k like he e ab ii g
for code, when the reality is that the organization ha a al ed
their need for technical writing. You get these technical writers put
i ii a d he he lea e beca e he e b ed. The , he
ga i a i hi k, Tech ical i i g i ha d hi e f , a d
We d ac all eed hi beca e e ll ha e he de el e
i e hi .
The e a gia , ga i g h le f k ledge ha i bei g
disseminated outside of groups that are writing technical
documentation. There are a lot of places that are doing the right
work, but there are a whole lot more places that are not giving this
fe i , I d a a e ec , beca e I hi k ha d
a little too entitled, but the seriousness consideration that it
deserves. In some ways good documentation is what sells a
product. Good documentation i ha ell a API. I ha ell
these things that these companies make a lot of money on. Bad

301
documentation is the reason that people choose not to use your
d c . Y ca b ild a g d d c e a i ea if d
k ha e l ki g f .

302
Matt Levine
Matt Levine is a columnist at Bloomberg where he writes Money
Stuff, an incredibly popular weekday newsletter on finance that is
widely read in the tech sector. Previously, he wrote at Dealbreaker,
and has written for The Wall Street Journal, CNN.com, and NPR.
While his substantial experience is entirely outside writing about
software, his techniques and insights are applicable to the work we
do.
How do you identify your audience and what level of background
do you assume for your readers?
I started out writing at a real financial industry blog. I thought of my
ideal reader as a first-year analyst at an investment bank: someone
who is 23, has a background in finance, knows what DCF stands
f , ha a ba ic idea f he l ,b d e k a lot of
complicated, specific details that I can explain. But, that has shifted
over time because I now write for Bloomberg, which has a pretty
mainstream audience with a core audience of financial
fe i al . I l ge a e ha I l ii gf r
fi a cial fe i al . I ha d. The e a e ic ha I i e
about market microstructure or high frequency trading or
something like that a d if I i i g ab ha I i i g f he
twenty people who care about it and do it. I have to assume a
certain amount of knowing what bids and offers are and stuff like
ha . I i g iei aj ali ic le he e e le ca
f ll i if he d ha e ha backg db e le
reading that are people involved in the trading world. I write a lot
ab ge e al ic a d he e I a e ha e le d k
ch he e ead he e ab he ge e al ic, a d I
going to be educating them more. To me, the core audience is
people who know a little bit about finance, who know what

303
valuation is, know what a merger is, have that basic grounding, and
ae e a .I i g e lai e a e f dee
structure rather than explaining the nuts and bolts, which I sort of
assume that they get.
How did you develop your voice or persona in writing?
When I came to Dealbreaker, it was run by a woman named Bess
Levin who had been doing it for years and was a comedic genius
with a very specific persona and style. I had never written for
publication before, so I was sort of mimicking that style. It was hard
d beca e he i a ge i , a d i i e ha eade
want. They want me to be my own person. I started off having read
blogs, having read Dealbreaker, but also having read Gawker and
the rest of the blog universe at the time. I was trying to imitate a
sort of Dealbreaker voice or a sort of composite blog voice, but
ha al a ha d a d f a ificial.
If j ief blica i e e da , ll de el
voice naturally. My perception was that blogging, writing on the
i e e , a like i i g a e ail f ie d . The e eall
better way to write naturally and in a conversational style that
sounds like yourself than thinking about your writing as writing an
email to your friends. I had experience writing emails to my friends
at Goldman Sachs and making jokes and trying to be funny while
also assuming a pretty high level of specific financial knowledge.
That was a useful experience to draw upon when writing for a
publication. In fact, I remember six months or a year into my job at
Dealbreaker having dinner with some of my Goldman friends and
e f he a i g, Y k , eall d like .
Y did ed d like he a ed;
d like elf. I ead a d I like eah, ha Ma .
That was a validating moment for me. When I write, it clearly is a

304
persona, but the main aspects of developing a voice is not so much
developing that persona but stripping away artifice and things that
e ied ick f elsewhere so that the writing sounds
more like your conversational style.
Whe a ee ac le ic, ha ce f
breaking it down?
One part that is really important to me is that I will read a
complicated thing and something will hit me on an emotional level.
S e hi g ill hi e he e I like, ha bea if l ha
a a a i g hi g ha he e fig ed ha a c a ick
he did l kh c l ed a d a ge hi a . I ill
have a reaction that is direc a d i ce al a d if I d ,I
write about it. The trick is that something intuitively resounded in
me that made me have that reaction and I want to create or explain
ha eac i f eade . I i g e lai all f he
things that ha e ed, I i g i he hi g ha a e
c lica ed ha d e e ha e i al ae he ic e.
I i i g e lai he i i e ge e le he
eac i ha I had. Tha ela i el ea . If e i g e lai
a complica ed hi g, e i d, i c lica ed. B if ha e a
strong, clear reaction to the thing, walking people through your
steps to get to that strong, clear reaction is an easier thing to do
because you feel it, you want to make jokes about it, you want to
e e i i a clea a . Whe i k , ha he ai hi g ha
happening. I have this experience a lot where some complicated
hi g ill ha e a d e le ill i e ab i a d a , Thi i a
c lica ed hi g. I ill ead he hi g a d a , Thi i
hila i . I a e e e le h i hila i a d ha
a ea ie lif ha j e lai i g i . Y e e lai i g ha he j ke
i a d ha a e ci i g hi g d .

305
What is it like to write about a topic knowing that some of your
audience will know more about it than you do?
I da i g. H e l , e a ec f a eg i ha I i e a
daily newsletter and I have built up some goodwill with my readers.
S e i e I ill j be like, He e i a hi g ha I d ge .
People ill e ail e a d e lai , I ade hi all da a d he e
ha e i i g. S ha ha e . I hel f l ha
newsletter is daily. Traditionally, in 2008, 2012, when I started
early on, there was a sort of tradition that a blog is something less
than a column. A blog is a thing where you write stuff on the
i e e , a d he e g e le ell , a d he e da
a , B , I g ha e g. The ake a e a li le bi
l e . Whe e i i g a e le e i h a b ch f different
items in it, which is what I do, the stakes on any particular item are
j ha high. I ea , he a e beca e d a libel
e e, d a be g, beca e he ll l k like
an idiot and that will reduce your credibility, but you can be wrong
occasionally. I try not to make mistakes, but you can miss a nuance
or admit ignorance when you have built up goodwill with a highly
technical audience who will kindly correct you. They will email you
a d a , He , I a fa , b g hi g. S ha a f
i , h gh i a e ba a i g hi g a .
O he i e, k ,I faj ali , I ll call e le. If
Id de a d e hi g, I ll call he e le h d
understand it and ask them to explain it to me. I find a lot of
e le a e e hel f l ab ha , agai beca e I e b il a
goodwill with an audience. I think that my talent is in taking
complicated things and explaining them in fun ways. There will be
a hi g ha I d k a ch ab ut as some of my audience,
b i ge e al f a die ce k e ch ab i
ei he . Mi e i a ge e al a die ce he e e le k

306
ab f he ic ha ch. I ll call a e h i a
specific subject matter expert in the thing, and there will be me who
is good at explaining complicated things, and between the two of us
we can generate reliable information. Again, doing it daily you
develop expertise by just writing about it and reading about it and
being in the conversati e e da . The he hi g i ha I d
ha e a eal a da e, if I eall d de a d e hi g I
i e ab i . I al ha e he abili , agai i a e le e
with a bunch of topics, I have the ability to occasionally write items
like, He e a e ha I ead. I d ge i tell me what
I i i g. Pe le ill e ail e a d ell e ha I i i g,
and that is liberating.
How do you find and evaluate your sources for validity?
Ia aj ali , b I eall a e ter. One thing that
ha e i ha e le ill call e a d a , I ha e hi ab
hi h ge ca dal a hi ba k. Of e he fi e i I ll a k
he i , I he e a bli hed ce ha I ca l k a ? Of e
times people will call me and say, The e i a idic l hi g
age 73 f he 10K f hi ba k. The I g l k a he 10K a d I
fig e if i i idic l . The fac al a e i ha e
aki g a e j f he c a bli hed acc a d he
al e e b i gi g i i i i gi a d e lai i g h i
idic l . Whe e le call e a d he a , I ha e hi ca dal
that nobody knows about at this bank, but you have to confirm it
ih e ce i e ie , I ll e d, The e a e e g ea
reporters at Bl be g h ill d ha . The I ill efe he
calle he e e .Id eall d i e iga i e k beca e
I ac l i .Id ha e he i i i al e g d
e i ga dId a .I a e lai ff e le,
spend a month diving into some secrets of a company.

307
I evaluate my sources through company filings and SEC
enforcement documents and stuff like that. If I write about a
criminal complaint, in some sense I will be evaluating the
credibility of the criminal complai i c l . I ll i e, Thi
d e d e, ba ed k ledge f he a he ld
k .I a e eId ha e e al a e he alidi f a c i i al
c lai . I d ha e a , I e if he g e e i
telling the truth he e. I l eed a e ha he fac ha he
government has brought the case is newsworthy. Quoting an
indictment will never get you in trouble for libel a lot of my
sources are just official sources and you can feel pretty safe quoting
them and using them for their intended purposes, within limits. If
someone gets arrested, you have to say that they allegedly did
whatever the government says they did. But you can sort of rely on
that a lot. You can rely on it for the truth of it, but not for the
interestingness of the story.
The answer to your question is that I almost never make factual
assertions based on what someone tells me, either with or without
attribution. Any factual assertions that I make I do so because I
know them to be true from long experience or they are public
record. There are exceptions where there is a complicated topic
a dI i g de a d i a d e le e lai i e. I ill
use that background knowledge as part of my explaining, which I
guess is kind of relevant to yo ca e beca e e alki g ab
ech ical i i g. If e a high-frequency trader and you work at
one of the six big high-frequency trading firms and you tell me how
he ech l g k , I e d belie e .I c a ,I ld
believe an as e i like, Ci adel i c i i gf a d Ci adel
i c i i g f a d. I d belie e e e h aid, Thi i
h I ld hi k ab h he de a k k , beca e i a
technical explanation, not a factual assertion.

308
You use a ton of block quotes. How do you decide what to quote
directly and what context to provide yourself?
A lot of that is laziness, unprofessionalism, and coming from the
bl g ld (la gh ). I feel like j ali , i ge e al, d like
block quotes. I like them fine beca e, k ,i j f
he bl ggi g hi g ha e i g c e he fac a he ha
put your own deathless prose on it. I often find they have a flavor
my writing is very conversational and sort of jokey and sometimes
i ice ffset that with legalese, like an SEC enforcement action
where everything has little definitions and quotes and whatever.
There is stylistic fun in jumping back and forth between a jokey
style and a very pompous block quote. The level of technical detail
that I tend to want to read in a story and then want to convey to
e le i j a li le highe ha j ali ic ie . I d
a i e, The SEC h gh he c a did a bad hi g. I
want to put in two paragraphs explaining exactly what the bad thing
that the SEC thought is and often block quotes are just more
efficient than me explaining it in a complicated way. The other
thing is if I write a lot of words I feel bad because I feel like people
have to read all of those words. If I put in a block quote I know
people can skip it he e ge i g a fla fi ih ece a il
eadi g e e d. If he e a l g al gc lica ed
explanation that I think the SEC or whatever source has done a
g d j b i h, I d a he e ha han go do it again myself. First
ff, i le k, a d ec dl , i ee e a i g f he eade
for me to do it again myself.
It sounds like a block quote in this context is like a code block in
mine.
I agree. A lot of my audience is in some way technical and is
interested in the technical details of these things. The block quote

309
is the equivalent of the code; they want to see the guts of the thing.
My commentary will be some sort of deep structure explanation or
some sort of joke or something, but I g i g ell he g i
a way that is more accurate or specific than what the guts are, so I
might as well just show them. Again, people can skip it. People who
are interested in the technical details are going to read the block
quote and people who are looking for the jokes can skip right over
he bl ck ea d i he j ke . I a ice a eg e
the readership.
Do you see your writing as storytelling?
I a e -narrative writer. I have my column, I write about
fi a ce, I d actually write stories I guess. A lot of what I do is
cover an enforcement action or a story about a trade gone wrong or
a story about some sort of disaster and try to imaginatively
reconstruct the sort of economic or human story of what that was
and give people a feel for how it would have felt. One thing that I
do that is embarrassingly non-journalistic is that I write imagined
c e ai e i e . I d i f El M k a l beca e he ll
d a c a hi g a d I ll j i he e a d hi k, H ld it have
fel be hi la e h i hi e b igh a d i g hi c a
hi g? I ll hi k h gh a h gh ce ha c ld ake
e e a d I ll i e i agi ed dial g e f i . Pe le l e i . I
just good jokes my job as a columnist is to get people to
understand things in a new way or to change how people think
about things or give people a framework for how to think about
hi g . The i agi ed dial g e i a h gh ce . I k i
how Elon Musk is thinking about it, but it ab h I hi k
ab h El M k c ld be hi ki g ab i.I a
demonstration of thoughts on a page.

310
A lot of it is storytelling. I wrote yesterday or the day before about
hi a ke a i la i ca e. I ead i a d I h gh , Ma ke
manipula i , ha e e . Wha fa ci a i g he e i ha ha e
this minute-by- i e acc fh e f li i be a ade .
The story was about this guy calling his broker literally every
i e a d a i g, F ck f ck f ck. He ad a d ha
because his boss is literally standing over him on a client call with
millions of dollars at stake and he has done a thing and the screen
ha da ed. S he calli g he b ke da e he c ee a d
he c i g a d i e i all ich. The e a news writeup of
it. The guy allegedly manipulated the price of pesos swaps by such
a d ch. I hi ki g, N , ha ha ha e ed he e.
Wha ha e ed he e i he g b i a di g e hi a d
he e c ea i g a d c i g a d he c ee da i g a d
he e hi e i all a d a a i el ich . Y j ell
people this is what it would have felt like. There are huge block
quotes of non-i agi ed dial g e, eal dial g e, b i j e ible
dialogue. I do a lot of trying to reconstitute the human stories of
he e fi a cial hi g b I d l hi k f elf a a
a ai e ie .I e e i agi i g, Thi i ha he had f
l ch he j ali clich . I l i g hel e le
think about things.

311
Mark McGranaghan
Mark McGranaghan created Go by Example, a website for
teaching the programming language Go. Go by Example drew
attention for its two-column design and quality example code.
Today, he works at Ink & Switch, a research lab that produces
reports and spin-off companies in consumer software. This
i e ie f e e l efe e ce he a e L cal-fi S f a e,
which came out of the lab. His call was the first interview I
conducted for this book.
Whitepapers are at the intersection between regular technical
content and more academic writing. Could talk me through the
process of creating one?
The e a ec he e be ee a a ke ec e hi e a e all
the way through to an academic paper. In the case of the local-first
article, that was more toward the academic paper side; in fact, it
started as a blog post but we ended up publishing it in a peer-
reviewed academic journal.
Wha addi i al kg e i c ea i g e hi g ha g i g
be in a peer-reviewed publication?
For a peer-reviewed publication in particular, there are a few things
that are important. The general level of rigor and clarity expected
are higher. An important part of the academic tradition is that
e acc e i g hi c f ka d he ld. I
important that you build on prior work, show how your work
relates to that prior work, and explicitly cite prior work where
relevant. Often you see people writing blog posts and making wild
clai alki g ab he i k, b he d ece a il li k
to the prior papers. There is an explicit process of peer review
where you send this article out to people who are experts in the

312
field who can provide feedback, and you make some amount of
adjustments to the article based on that feedback. Eventually
people agree that the paper is good to go.
Regarding the local-first paper in particular, you did a lot of
example projects based on the principles. What was your and your
co-a h a ach b eaki g d he e c le jec a d
presenting them in the paper?
The context there is that this paper emerged from a stream of work
in which we were following a hunch, or pulling a thread, about a
a ha f a e c ld k diffe e l . We a ked, Wha if he e
were all of the benefits of desktop software and all of the benefits of
modern cloud software i he e a a ge b h f h e? Wi h
the examples, we were able to show what we had done and what we
had learned and how that played forward into the architecture and
approach that we were suggesting.
What was the process for creating Go by Example?
I believe programmers learn code by writing code. The most
productive way to start writing code is to have examples. There is
ba icall igi al c de i he ld; i all e a ia ff f
the family tree of code. I wanted to have a way of documenting
f a e ha e b aced ha . A ch a ible, e h , d
tell.
The idea with articles on Go by Example is thinking about the key
ac ical hi g ll eed d ie g a .Y eed
declare variables, do math, have string manipulation, read/write
files, things like that. As those things came up in the course of my
Go programming or my experience with other languages, I would
ake a e f ha a d he I d i e he e a le. The e a le
will be as self-explanatory as possible you might have one line that

313
says this is how you read and write files. But, you might have some
hi g ha a e f ll b i , like he e igh be li le flag ha
you can put in there or some gotchas in the API so you have to
explain those. Basically, I try to start with a concise program that
fully demonstrates the feature in an accessible way and add
commentary where necessary around it.
Is Go by Example a recipe book?
Sort of. When I think of recipe-book documentation, I think of,
f e a le, H d OA h i h a Rail A . I a ecific
business use-case: how do you add A and B together for a specific
g al? I hi k G b E a le i ki d f i ha ei , b i le
about ready-made recipes that you can use right away in your own
end use-case programs and more that these are the building blocks
f k. I a be le a eci e a d e a ca al g f
ingredients. The expectation is that Go by Example is for
experienced programmers. People know how to combine things,
a d e gi e he he b ildi g bl ck he e l ki g f .
Go by Example is designed to teach experienced programmers a
new language. How did you decide to go after that audience?
Whe I a ed G b E a le, I did k e ch G . I
knew a little bit, and I taught myself some in the course of writing
it. It was where I expected most Go programmers to be coming
f beca e i a la g age ha I hi k e le a
programming in. I think people tend to start programming in
JavaScript or maybe one of the web languages like Ruby or maybe
one of the classic enterprise languages like Java. It seems like a
weird language to start with, so I figured people were coming to it
with prior programming experience.

314
I also wanted to explore this idea ha he e ch ha
ga e eed i ca e . The d eed alk ab
ha a a a e, he he f a a ; he d eed ch
besides the thing you type in your editor to get an array in Go.
They already know what everything el e ea . Tha he ecific
angle I wanted to explore with that project.
Go by Example has a two-column layout versus inline code. Why
did you make that design decision?
I thought that would be the most useful way to see it as a reader.
Part of the idea is that you have this complete program you can
copy and paste the code column, put it in you editor, and you can
i.Y ee e ac l ha e i ed. A l f e le d e e
need to read the text, maybe only the FYIs and gotchas. For some
of the c e e le a , Thi i he eigh ee h i e I e eed
look up regular expressions in Go ha he hi g ha I eed
c a d a ei g a ? Pe le ell e he efe e ce
the site for stuff like that. Of course, the text is side by side with the
code, so you can see exactly what the text is referring to in a clean
a . I al a be e fi f de k f fac , he la d ca e
c ee ha e le e d be i g he he e ga i g,
versus a one-column layout that tends to be better for phones. It
felt like the right way to do things and part of the idea of Go by
Example was exploring a different type of documentation.
Another important design decision: every single piece of code in
the site is in the context of a fully executable example. Often you
ee he e a icle ab ga i g a d he a , He e, add hi
li e c deba e a d e de i g, Wai , he e d I
add it? Do I need to do anything else? Do I need to import
e hi g? Wha e he e i e a h f he lib a ? The e a e
a li le hi g ha a e ece a il c f i g if d

315
have the full context there. I wanted to have it so that every
example was fully executable and there was no orphan code where
people are wondering how to use it in a real working program.
Did you monetize Go by Example at all?
Not directly. Part of the idea with the site and online writing in
general is that I think good online content has extremely high
equity value. The Go by Example site is accreting value over time,
e e h gh I ki g i ha ch he e da . E e
year there are more visitors and every week or so someone emails
e a , Y i e i g ea . S cca i all I ca ake ad a age
of that equity value. When I was applying for a job a few years ago,
e le c ld ee ha I d d e hi k a d a , Oh ha ki d
f i e e i g, he ki d f k ha he d i g. If I e e a ed
to do a business around Go or for developers or any sort of
ech ical c e , I c ld e hi g he e. I m sure I could put
e hi g like ad ha e e , b ha i ee i g e. T
me, the real value is in the equity, which you can take advantage of
in certain specific, unique ways over time.
How has writing affected your professional career?
With Go by Example, I get a lot of good feedback and it might
ha e hel ed he a gi i a fe ca e , b ha a jec I
mostly did for my own edification and because I believed that
e hi g like ha h ld e i . I h gh ha h a l e
documentation should be written, and I wanted it as proof. Sure
e gh, ll ee ha la g age ha e e fXb
E a le fl a i g a d, I ha ihi f ha e ec .
Online writing in general can be incredibly valuable professionally
a d I e ee hi i h i e . I ha e a ela i el de
online presence. Right now I have a few articles on my site, but I

316
get all kinds of interesting inbounds, people who write about stuff
ha I e i e ab . Pe le a alk ab i , they want to
lea e, a d he a ee if he e a i
collaborate or work together. That value compounds over time if
you do it right. I wrote Go by Example six or eight years ago, but
that continues to generate and deliver value to me e i e. I a
h ge fa f i i g li e a d i g b ild , e e if i l l ,
e ki a e. I a i i ic ab di ec l
monetizing with things like ads, but if you have traffic and
credibility and PageRank juice, you can use those in all kinds of
interesting ways down the line.
How does Ink & Switch approach writing?
Writing is probably the most publicly visible export from the lab.
What actually comes from the lab is tacit knowledge from the
heads of people who have worked there and the relationships,
network, and spin- ff , e f hich I ki g . Tha
said, writing has done a few things for us. One is that it forces us to
understand the topics. Part of the idea with writing this local-first
software article, for example, is that we had a hunch, and we
pursued the hunch for a year or two. We started to get some
results, and we felt that it was more than a hunch it was an idea
that was getting fleshed out. We wanted to test that by trying to put
it to writing.
Whe ie e hi g, a eali e ha d f ll
de a d he idea, ha e cla ified i i he i d. The i
becomes this sort of beacon. There are a fair amount of people
i hi he bi f he lab, a d j ha i g a a e f i , l cal-first
f a e, a h ge. Pe le ca a alki g ab i a d a
coalescing ideas around it. Once you have the draft paper and

317
ha e i i e all , e le a e ddi g hei head a be he e
c a chi g hei head a d i all ef l i f a i n.
Once we published the idea, we got all kinds of interesting stuff
coming into us from that article. We heard from people who were
working in the space, who had apps that were starting to use the
ideas, who were doing academic research, who were thinking about
doing startups, and who were curious about the lab because of what
they read. The article acts as this beacon that brings people to the
ga i a i . Al , i hel i h hi g like ec i i g. Sa e e
trying to hire someone for one of our spinout a d he e i g
that local-fi i ci le, e ca j a e e i g d hi
he e hi i he a icle. Pe ha he e e e al ead ead he
article, which is easier than trying to explain local-first to them from
scratch. If you had never heard about it, it would be kind of crazy
and would be incoherent.
On your website you list media as one of your interests, stating,
I di a i fied i h he li e bli hi g a f acke ,
ads, and content mills, and am looking for better technical and
ga i a i al del . C ld elab a e?
The thing that I dislike about the status quo is that you go to these
sites and they do literally hundreds of HTTP requests. If you go
and open washingtonpost.com this is one I know because I used it
for my slow software article with your browser tools open and you
go to the networks tab, it will make hundreds of HTTP calls for
one article with a few images. It just feels kind of gross to me. If
l k he e i calli g ,i Faceb k a d G gle and
DoubleClick. Is this really all necessary to read an 800-word
a icle? Of c e, i l . I ake he age ji e a da d
efl he i l adi g. A l f he c ee i all ca ed he
content. It makes the content hard to archive, and if you want to

318
ca ea a h f he age, i a e . I al e
susceptible to various types of internet outages. I think there are
reasons for why this happens in the context of the business side.
The model that I like is where you statically generate something,
put it in HTML files, then put it on S3 or similar, put a CDN in
f f i like Cl dF , a d he ha i . A a e d a
bill f f d lla a h, a d he i e e e g e d .I
a e e. Tha ha I e done with Go by Example, which has
allowed me to basically forget about the site for a year. Meanwhile
he e e all ki d f ild hi g ha e i g he e, like he e
crazy SSL vulnerabilities and all of these cloud platforms going
down, and I never have to worry about any of that because it is a
i le a ic i e. F he e , i a e e beca e i e
super fast.
There are about three HTTP requests to load a page on Go by
E a le, e f he age, e f he CSS, a d I hi k he e
one for the li le g he . I e i le. Tha ha I like he
technical side. I think you can get quite far with just hand writing
the HTML. On my personal site, for example, I hand write the
HTML and the CSS. These are in a directory, and I rsync the
direc S3, e e iall ( he e a c e i ale f S3), a d
he I all e . Wi h G b E a le i a li le e
hi ica ed i ha he e a lchai ha ge e a e he i e. I
the same basic idea: you produce a public directory that you host
li e. I a h ge fa f ha a chi ec e. The e a e a l f a ic
site generators, but I tend not to see them embraced by media
companies per se. I see them used for personal sites and such.
O ec a ha I e c aged b , al h gh I ha e used
hei d c a dI a e e b a ea , i Gh .
Ghost is this independent publishing platform I d k

319
what extent they embrace that static site idea in particular, but they
are at least with media companies that are less reliant on advertising
and more using things like subscriptions.
On the business side, I find advertising incredibly unsatisfactory.
I ki d f a bad ba gai all a d beca e he e gi e al :
he ali f hei e e ie ce a d hei i ac . Y ca make
much money with ads because you need an enormous amount of
traffic for ads to make sense, and the content needs to be cheaply
d ced. Tha h ge c e fa . The e a ea
answer for how to pay for this stuff because media tends to be a
blic g d, e hi g ha ce i he e be efi a l f
e le h a e di i cli ed a f i . I ki d f a c d
in that respect and a bigger open question on the media front.
For the case of individuals, I think you can absolutely justify it
though brand equity. It might take you tens or hundreds of hours
to make some content, but the potential brand equity, if that helps
ge j e j b i he e e ea , i h i . I hi k i a l
easier to justify for individuals.
I he ld f ad I e b lli h hi iche ad
networks less Google-style targeted ads and more unique
sponsors.
Y al i e, I ec -text media is underused. E.g., I
hi k e eed e c ic ab ei ic . C ld
expand on that idea?
I ge e al, i h edia, e e c i ed e he a
over the past few decades even as things have completely and
utterly transformed under the industry. The technology capabilities
and the business model landscape have been completely blown up.
I see us trying to transliterate the old world into the new world.

320
You have these online newspapers that are writing columns and
elli g ad agai he a d .I i i g he i f ha
ca d li e. I e I feel as strongly about this with
e ec ech ical a icle , ha a d ai he e e ca be
uniquely good.
Part of the insight here, and again this is potentially less relevant to
ech ical a icle , i ha he e a ki d f l i lica i ha eed
to happen when you think about the impact of your work. The
number of people who are inclined to consume it is a function of
how accessible it is, how entertaining it is, and things like that.
Then, how many people retain the message and act on the
message? In the case of public-interest media, the stuff you would
ee i a e a e , i ha d ge e le ead a 1000- or 2000-
d a icle if he e eall i e e ed i he c e . Tha i a
i e he e f edia. I a e hat is as
relevant for technical content because often the audience is
professionals or aspiring professionals who have a specific goal in
i d, he e ac all i a ed ge h gh he e .
F e a le, e hi g I e al a a ed k i creating a
more dynamic medium that adapts to your learning.
https://www.executeprogram.com is doing this right now with
JavaScript. The idea is it knows what you want to achieve and from
that gives you what you need to learn to achieve your goal versus
giving you a whole big list of things that you may or may not want. I
think there are opportunities to do stuff like that, especially for
i ga i g a ea he e he e a l f l e. Tha
a i e e i gf ie a d I e ci ed ee e le e ploring it.
I he e a hi g el e d like add?
He e e. The e i a i c edible dea h f high-quality technical
content on the web. The flip side of this is that if you write good

321
content and present it in a compelling way, you can get a lot of
traffic. I noticed this with some blog posts I wrote a while ago and
a icle e e i e f I k & S i ch. If l k a he e i e
i e e a dh a g d a icle a e i e e e da , i
many at all. People can write good content if they sit down and put
hei i d i . I i a ei d hi g d beca e e ii gf
e i i iall . I a bi f a lea f fai h a e ha if
write something good, somewhere between a thousand and a
million people will come and read it, but i e. I ld
encourage people to try taking that leap they might be pleasantly
i ed if he ie e hi g ha i high ali . I d e
eed be h ; e le ill ead l g ff if i ele a hei
interests and helps them with something they want to do.
I guess one other thing I would say there is we often overestimate
the expertise or the knowledge of the general public in terms of
e hi g ha e e ki g . Ma be e bee ki g ,
to use an example from earlier in our conversation, OAuth
authentication in Rails for the last three weeks. Well, you are now
at the top 0.01 percent of programmers around the world at
OAuth authentication with Rails. It might feel obvious now because
you spent three weeks working on it, but approximately everyone
el e ha idea h i k .Y eg di c h feel
about your own level of familiarity and how obvious it is because
e bee ki g i h i . Y igh be lea a l i ed if
you write something that seems obvious to you. You might get a lot
f e le h a , W I did k h ha ked a d ha
i e hel f l. D be di c aged f i i g ab ic
that seem obvious.

322
Patrick McKenzie
Patrick McKenzie has been writing on his website, kalzumeus.com,
since 2006. He has written over five hundred articles about lessons
learned working on Bingo Card Creator, Appointment Reminder,
and Starfighter, consulting for large software companies on
engineering and marketing, and most recently working on Atlas for
Stripe. He is also the third highest-ranked user of all time by
upvotes on Hacker News. Patrick called me from Japan and we
spoke for almost an hour.
In 2014, you wrote an article about Heartbleed and how good
marketing to engineers was very effective in encouraging the
community to step up and fix the issue quickly. One thing that you
aid a Geek ei e d like i he ech ical fac a e
de c ibed i a e i all e ca i e a e . Whe d
hi k i a ia e ick ha le a d he d hi k i
appropriate to break it?
It depends on your audience and the context for it. If we flip back
to 2014 with the context for Heartbleed, there was an extreme
vulnerability in a piece of software that was widely deployed to
critical applications the entire world over, and we had a very short
window of time to update that piece of software, within literally
single-digit hours of the news breaking. This needed a worldwide
coordination between people at hundreds of thousands of
organizations. Achieving both the consensus for that worldwide
organization and then actually going the work would be a difficult
thing in the best of times and it needed to happen on a timeline
that was objectively unreasonable. For the marketing approach,
they needed to correctly convey that level of urgency in a way that
both technical decision-makers and non-technical decision makers

323
could grasp to suggest that they should drop what they are doing
right now and get on the Heartbleed problem.
Na i g i The Hea bleed P ble i he first emotional nuance
of that incident. The typical way that vulnerabilities are named is
something like CVE-2014 and four random digits. But, if you go to
CEO a d a , S , b , I eed c le el bl a a
the schedule for this week and I will need 200 engineers to do a
crash project on addressing CVE-2014-1234, i i likel ha he
CEO f he c a ill a , Oh e , ce ai l , ha i a .
But, if you show them the website for Heartbleed, which a) is
called Heartbleed, b) has a hundred-dollar bleeding heart logo, and
c) says that accurately technical fact the world will be on fire
if e d d ha e e d i g a d fi hi , ha ld
be much more likely to get approval for an urgent course of action.
With respect to writing, you should write in a knowledge of who
your audience is and in a knowledge of what you want them to do
with your writing. If you were writing to communicate technical
facts to other technologists about under-the-hood plumbing,
ge e all e g ing to be writing a little more on the dry scale
and maybe mixing in some humor to keep things interesting, but
avoiding polarizing claims generally. Specifically, when writing for
technical audiences I tend to avoid making claims that are true-ish
but difficult to track directly back to concrete evidence. A claim
that is true-ish is that Heartbleed had a twenty-four-hour window to
update things in the entire world. Somebody might sensibly
de , H d k i a a e -four-hour window and
not a twenty-two-hour window or a twenty-six-h i d ? Wha
he c ica i fe i al i e ld a i ha he
important part about that statement is not the specific number of
hours; the important part about that statement is to get people
thinking that this is an urgent issue that needs to be addressed

324
immediately rather than something we can deal with with our
standard processes that have lead times of, for example, six weeks
a e . B , he alki g ech l gi , if ake
claims that have numbers in them, they generally believe those
numbers to be reasonably concrete. If you establish an expectation
with technologists that when you say a number it is and I will
report but not endorse this word bullshit, then they will largely
discount your claims not only with respect to numbers in the future
but also all other factual claims you make. Know who you are
alki g , k ha e i g ge he d , a d e he
appropriate amount of emotionally laden communications to
achieve your instrumental goals.
I he a e a icle e, Ma ke i g hel acc li h
legi i a e g al . I hi k he e a e defi i el a a e ial be f
engineers out there, including some of my friends here at college,
who would disagree with that statement. Could you support it in
the context of engineering and technical communication?
I ll ad i ha he I a a ge e gi ee , I a al hea il
skeptical of the value of marketing, PR, and sales. I think it is a bug
in the engineering community tha e e i i i all ke ical
of all of these things. We build things that make the world a better
place. Given that we build things that make the world a better
lace, i fe i al e ibili a e gi ee ac all ge
them adopted or we are not maximizing for the aggregate impact of
the things that we have built.
Take sanitation, for example. We should prefer a world that has
fewer Cholera outbreaks to a world that has more Cholera
outbreaks. Getting people to adopt sanitation is fundamentally a
marketing and sales challenge. You need to successfully convince
people that one, science says if you adopt sanitation you will have

325
fewer Cholera outbreaks and therefore your children will die less
frequently, and two, since science says that, you should actually
change your behavior to, for example, not pour excrement down
the town well. That is one of several hundred years of examples of
successfully marketing an engineering artifact for good.
If ea ac a ha i d ci g a aluable thing in the
world, then the day-to-day activity of the company should be
successful execution of marketing and sales processes to achieve
highe ake f ha hi g ha e d ci g f he ld. If
you are working at a company where your engineering labor does
not increase the aggregate amount of value in the world, quit,
today. Work on something better. Once you find that better thing,
devote an appropriate amount of time to the marketing and sales of
it to get it adopted and maximize value creation.
I ge e al e , ha ii g ce ?
I often get asked about my writing process, and I also ask other
writers who I respect about their writing process. The writing
ce e d be i e el e al each i e , a d I d
nece a il k ha i i ge e ali able. I d i e i he a ha
some of my favorite writers write, nor have I been able to teach
people successfully how to write in the way that I do. I have
generally been unable to operationalize things that people have
attempted to explicitly instruct me on with respect to making my
writing process more effective.
That caveat out of the way, I typically start with a high-level
overview of the general topic of the piece that I want to write.
When I was younger I had fewer constraints on what I wrote about.
The e da he e ge e all e f b i e a i ale: I
ld be eall g ea if e had a iece ab a ic. The , I ll
over that problem for a while in the pre-writing stage. Often the

326
mulling involves a lot of shower-thought-time about it and reading a
lot of literature that has been written about the subject already;
sometimes it involves a combination of reading the literature and
reaching out to people who would know more about the subject,
just for informational interviews.
The purpose of an informational interview for me is to just take
notes on what they have to say. I often throw out some of my initial
ki g h he e . I c e l i i g a iece ab i ae
equity in the software world and so there are a number of people
who I know and respect who have professional backgrounds within
i a e e i . S , I aid he , S e f he hi g I hi k a e
likel e ab ha I e b e ed e he a c le f ea
are X, Y, and Z. What d a i e e ha ? I e
ca e he a , Ye , ha i a acc a e del f he ld. I
e ca e he a , Y e ide ified he ,b d
understand the underlying cause. So let me tell you about how
private equity LPs would think about the thing that you just talked
ab he ed ce i d be .
This testing and gathering phase continues for a while, until I feel
like, Oka , i b ad ke I k he a ach I g i g
ake hi iece. The , I get to the extremely non-replicable
portion: I sit down at a desk, drink a lot of coffee, and write like a
man possessed for six hours.
Id edi i g a e he hi g ha I e j i e . The fi
editing pass largely focuses on the flow of the piece. One thing that
I do during that is to read the piece out loud and see if it makes
sense at a narrative level. If it makes sense at a narrative level, great,
and if not, I re-arrange sections, maybe thicken it out, attempt to re-
write the conclusion. My conclusions are always the weakest part of
my pieces. Once I have the piece flowing rather well, I do another

327
re-read focusing more on a sentence-to-sentence level. Is the piece
a well-c af ed a ifac i he E gli h la g age? While I d i g ha
I also check for spelling and punctuation errors.
After that, candidly, most of the time I move directly to
blica i , hich babl d e a i i ef b i e e l .
O e hi g ha ca d , a ic la l if e d i g he
informational interview step, is to take the final draft of the piece
and circulate it to the people with whom you had your
i f a i al i e ie a d j a , He , a a FYI, I
la i g bli hi g hi e eek. I de i g if ha e
a c e i? I e ca e he ll gi e c e ha
you would actually incorporate into the piece. The shadow reason
to do this is that the experts that you have in your network have
other people who are interested in this topic in their networks and
when you publish a piece that they were perhaps quoted in or
materially influenced the direction of, it is likely that they will
choose to amplify that piece into their networks. The other thing
you can do is talk to people who were not involved in the creation
of the piece and j a , I e ec i f ie hi
matter d ha e a c e f e? If ha e a all
community or ecosystem, it sometimes makes sense to get people
jazzed about the topic for the day when it goes live. This is
assuming that your primary mode of publication is doing
a ch la che f iece he i e e . Tha i he
only publication mode that people have to worry about: in some
cases you publish to private audiences, like inside a company; and
in some cases you might have he iece blica i be
synchronized with a business event, for example. In the mode
where I have large amounts of ability to determine exactly what day
the piece hits the internet, this is the process I use.
What makes a technical article good?

328
There is a spectrum of form factors that are involved in technical
writing. Some of them are how-tos, some of them are tutorials, and
some of them are a GitHub READMEs, which just tell you how to
use a piece of software. Their goals are very different. The
common goal that I hear from people who are writing for career-
oriented reasons is that they want to burnish their technical
credibility with respect to a topic by writing something that is useful
e le h a e e c e i g he ic fe i all . Tha a
reasonable goal to center on for the purpose of giving this advice.
A lot of pieces in that genre are heavily improved by having a better
a a i e f he iece ha j e f a e X c bi ed i h
idea Y. Pe le e d de al e ba ic i f a i n. Say you
ee ie H e WebS cke i h NSQ e e, he e
WebSockets are a way to get information from a server to a client
browser asynchronously without the client having to request the
additional information, and NSQueue is a queuing technology. If it
is just WebSockets plus NSQueue, a lot of people will assume that
is a one-on-one level article. In fact, that is plausibly an article that
an engineer could write in their first year of being a professional
engineer. For me, it was an article that I spent days of my life at my
la a ki g beca e I did ha e acce i.I a
working on the article; I was working at the intersection of those
two technologies and banging my head against the wall.
The better way to write that article is to start with a motivating use
ca e like a chi ec i g a eal- i e cha a a d he g he
ech ical de ail ab i . W d like a chi ec e a d eal- i e
are high-value words within the community. Because a chat app is a
use case that anyone can quickly wrap their head around, you have
a c ce al f a e k f de a di g, Oka , ha i he
thing we are actually trying to do with WebSockets here and why
d e i ac all a e ? Wh ld e be i g NSQ e e? The

329
 ea d be ing NSQueue is at the scale of a social network,
the number of messages flying over the wire is extremely high. The
ea e d i g WebS cke i beca e hi all a i e
scalability for an arbitrarily large number of clients without blowing
out e e bill. G ea , le alk ab he ac al
implementation details of the glue code that you write. The general
information architecture that I use for pieces like that is peeling
back layers of the onion arbitrarily deep. You start with that super
high-level explanation of the goals of doing this, and then you
continue unwrapping the onion one layer at a time until you get to
he e b f i he e e h i g e le ac al c de
snippets.
I try to keep most of my technical artifacts sufficiently technical
such that there are actually code snippets or configuration written
i he . Thi i a l beca e I hi k i ef l f
somebody that is following along on the internet and partly because
it maintains technical credibility, which is something that is
e e el i a if e i i g f ech ical e le. Y
d a be b acke ed a this might be kind of controversial
people writing technically do not generally want to be bracketed as
technical writers. Consumers of technical writing such as engineers
often feel that professional writers in tech are quote-unquote not
technical. I think that is a) unlikely to be a materially true belief,
and b) is injurious to the interests of both the engineers and the
people writing professionally. Be that as it may, it is a common
belief in the community.
Thus, one reason to include more code or more configuration
snippets than you otherwise would in technical writing is to signal to
ai akeh lde ha Ye , I a al a ech ical person just
like .I h ghl de a d hi . Tha e , Ia ii g
something that was understood and digested for me by another

330
 e . G a ed, he e i hi g g ih ii g e hi g
the basis of understanding that another professional has provided,
b he e d i g hi f ca ee ea fe a
burnish your personal expertise.
A good article allows people to select the level of detail that is
i ee i g he . If e hi ki g f i i g he a e ic
repeatedly, you can have pieces that are at different points in the
detail spectrum so much might be heavily code-oriented, so much
might be more architecture-oriented, so much might be more of a
business entry to the joys of queuing systems. Then, use the magic
of the internet to interlink those together and allow people to select
which of those is most relevant to their interests.
I d like a icle e i 2010. O e a ab
using SSL in Rails it was very much the type of article you were
previously describing; it has a goal, a bunch of code snippets. The
other one was a post on how to reliably architect a website for small
businesses. Rails has changed a ton in the last ten years, whereas
even in a post-AWS world your website reliability article is super
relevant. In the face of how quickly technology changes, how do
you make your content evergreen?
I e bee ii g fe i all i ce a lea 2006. I e a l f
cycles early in my writing career writing things that depreciated
quickly, in the economic sense. For example, writing about the
current best practice on Rails, especially back when Rails was
moving at rapid speed, did not set me up for long-term
professional success. I would probably not write on that topic
today, particularly not if I was writing in a concerted fashion. The
reason for that is that, as you mentioned, there are some posts that
maintain their value after ten years and then there are some posts
that are, like the Rails article, probably good for about eighteen

331
months. Eighteen months might sound like a long time. There are
many written artifacts that lose more than ninety percent of their
value within twenty-four hours. I like to say that The New York
Times throws out more excellent writing than you will produce in
your entire career every day because the value of the ninety-fifth
percentile New York Times piece after forty-eight hours
approaches zero. Given that you are vastly less resourced than The
New York Times and you probably have a longer scale with
regards to your decision-making horizon, you should intentionally
try to get more of your pieces into the bucket where they will
continue to be valuable for years ahead.
You can intentionally optimize for that by writing appropriately
crunchy pieces about technical topics that avoid the minor-level
implementation details. That goes a little against the advice that I
just gave you. If you treat the implementation details by wrapping
them in an abstraction, then you can link out to the article about
the abstraction. Then your piece about the architecture remains
relevant even if the link to the abstraction needs to get updated or if
someone following the link would find something less than
optimally useful. There are many, many, many things that people
have to learn that do not materially change over the timescale of
decades, even. This September, a lot of teachers will start to teach
high-school math, and calculus has not been updated all that much
since last year. I predict the curriculum for calculus a year after this
will be pretty much the same too. There are many professionally
relevant things that I write that are of a similar unchanging nature.
In 2012 I wrote a piece on salary negotiation advice for engineers,
and because I was writing on blog software and blog software
generally includes the date prominently all over the piece, I
i el ge e i ab ha iece a ki g I hi ad ice ill
g d? Tha a f ai g e i f e be a ked: f c e

332
the world has not advanced so much between 2012 and 2020 such
that not negotiating your salary is suddenly a good idea. The thesis
of that piece is that you should always negotiate your salary. Just the
fact that I made the date so prominent in the piece caused people
to believe that as soon as the date changed, which happens literally
every day, then the piece starts losing value. I am more intentional
now in writing to position my pieces as essays rather than blog
posts, because essays have an anchor around timelessness and blog
posts have an anchor around being up-to-the- e .I
intentionally writing most of my essays on subjects that will
continue to be relevant to my readers in ten years.
I try to write the depreciating content for clients and keep the ten-
year stuff for myself. The clients k ha he e b i g he e
in the business of putting this out. What about the business model
of these larger content publishers allows them to purchase this
rapidly depreciating content and still build a business on it?
There exist publishers of technical content that either have much
better monetization options with respect to one reader than an
independent writer of technical content would, or they are selling
something that is not itself content and so their investment in
content is essentially a marketing expense for the core thing. For
example, I work at a large software company. The core economics
of large software companies are extremely healthy. The market
characteristics of my employer are a bit different than the typical
enterprise software company, but the typical enterprise software
company might have margins approaching one hundred percent
with deal sizes in the five or six figures. They can justify an awful lot
of spending on a daily basis to produce content if it successfully
gets decision makers for their industry to get in touch with the sales
e . Tha d e k ie ell if e a i di id al
engineer yourself and you have some allocation to make of doing

333
core billable work versus investing in your own marketing; you
would generally want to write artifacts that would continue having
value even in weeks or quarters where you were primarily doing
billable work.
The other thing I will mention is that not all firms make correct
choices. Especially in media right now, and a lot of publishing
industries, for historical reasons they are sort of priced in to writing
content that depreciates very, very quickly and that might be
b i al. I d a a e a e , b he e a e e
extremely talented writers I know who would probably, finger to
the wind, double the enterprise value of their writing if they re-
allocated ten percent of their cycles to producing things that had a
five-plus year horizon on them rather than the current allocation of
things that have a one-to-two week horizon on them.
I 2006, ea i led, Te Rea Wh M I e e
W i i g I Te ible. I bee 14 ea i ce he how have your
perceptions changed?
I h a i g a he a ha he f a i g f ha a icle a ha
I hated listicles. I continue to hate listicles. It is important for
ie de a d ha eb ha d ce a d c e f
writing on the internet, and that the writing that actually makes it to
you to consume has a particular economic engine generating it.
The incentives of that economic engine are not your incentives.
Much writing on the internet is written by machines that are
optimized for producing dross at scale. I would put BuzzFeed,
uncontroversially, and The New York Times, much more
controversially, in this category. This is writing optimized for
generating page views to sell to advertisers. The economic
incentives of someone who is operating on a per page view model
are that they will want to maximize for engagement based on, for

334
example, clickbaity titles. They will want to have the piece written
by the cheapest professionals they can possibly get to write the
piece. These professionals are probably not experts in anything in
the piece, even if the brand halo of the organization suggests that
they are probably experts. They will iterate on formulas that
repeatedly allow them to write their quota of pieces every day, with
pieces being strikingly similar to each other. These strikingly
similar pieces are then read by strikingly similar readers for
s iki gl i ila ea , b he b a d i i i g ill be: Oh,
, T e da i e i el diffe e ha M da .
Thi de i e he fac ha T e da ha ba icall del a i
i igh e M da .
This is most of what you read. Most of what you read is terrible. It
is terrible as an artifact of the English language. Listicles are
generally not very well written; they tend to avoid all craft and joy
beca e f he a he a e d ced. I e ible i h ega d
the underlying advice not that most listicles actually have advice
he e icall i e b e e ,d ha e ch i e
involved in actually battle-testing the advice, and are not
incentivized for getting their recommendations right. The writers
are offered incentive to create something that will spread. Clickbait
fe a e e e ci e e le e i al b , a d ill
kee ge i g be e a hi g e le b . B clickbai
publishers do not need to invest years upon years of their time on
actually giving advice that moves the needle for professionals.
Anyhow, so, much of the writing on the internet is pretty bad.
Your mission, should you choose to accept it, is to find authors
whose writing is actually good and model your writing more off of
their writing rather than modeling it off of the writing that is likely
to come across your desk passively. I think that the prestige
function for writing in a lot of industry is determined by legacy

335
institutions. One of the core terrible insights about legacy
institutions is that the difference between BuzzFeed and The New
York Times i i a il ha he hi e diffe e e le, i
i a il ha he ie diffe e ic , i i a il ha
The New York Times has checks and balances where BuzzFeed
does not; the difference between BuzzFeed and The New York
Times is that The New York Times has been BuzzFeeding for a
few centuries longer. That is one of the most cynical things I will
ever say about the state of the world, but I am forced to believe it is
true after decades of experience that supports it.
Could you give me a comment on Hacker News and its role in the
community?
At one point I was the number two user on Hacker News. I might
have slipped down to number three, largely as a function of being
b i h life i he la c le f ea . I i i e a de a di g
j b a d ha e all child e , I l ge i a ii f
posting every day. I think that people underrate Hacker News
massively. I think there is a meme in the community that Hacker
News threads are populated by toxic commenters and that it is a
ceaselessly negative place such that the world would be better
without Hacker News in it. I think unequivocally Hacker News is
an extraordinary venue for value creation throughout the world,
largely by bringing together technologists who would not have
otherwise met each other. There are people who make lifelong
relationships from that site. I met my former co-founders there;
Thomas Ptacek is one of my best friends for life; and it feels
extremely unlikely that I would have my current job but for Hacker
News. I think you could say that for many people who are nowhere
close to being quote-unquote on the leaderboard.

336
Hacker News helps disseminate ideas, like my ideas on sales and
engineering career optimization and the body of practice that is
dealing with venture funding, both from the startup side of the
fence and from the investor side of the fence. These things would
be difficult to get access to unless you had a high-quality social
network that already had an expert about them in it. It is basically
one step short of miraculous that you could find George Grellas,
who is an expert Silicon Valley lawyer practicing for thirty years,
and have George Grellas patiently walk you through the impacts of
the changes in the independent contractor classification in the wake
of Microsoft abuses in the 1990s. By the way, George Grellas was a
practicing lawyer for Microsoft. That I could read that as a person
who was newly an independent contractor working in central Japan
in the late 2000s/early 2010s is one step short of miraculous.
I ll ack ledge ha he e a e ce ai h ead ha a e ge e all l
quality, mostly things that are removed from the core interests of
he ech l g i d .I a a ic la l g ea a e i g h le
talk about politics, for example. But, for the things it does well,
Hacker News does them better than plausibly any place in the
world, and the fact that it defaults to open is an extremely powerful
defa l . I hi k ha i b adl bee ge i g be e a a e l f he
new moderation regime, under Dan and the other new moderators
since PG handed over the reins. I wish more people who could get
value out of Hacker News were active there.
Your most famous piece is on salary negotiation. I was at dinner
tonight and I caught up with a friend who is moving on when he
graduates to a large software company. I told him I was talking to
a d e hi he iece, a i g, i he c e f your career,
correctly applying this is probably worth on the order of a million
d lla beca e i hi ca e he i e e killed. Wha e i
writing the piece and why do you think it did as well as it did?

337
I wrote a piece in 2012 about salary negotiation. Approximately
five hundred thousand people read it every year, even eight years
la e . I d a a hi i a a ha ake e d
highfalutin, but broadly the piece is designed to be the last word on
salary negotiation for engineers. Tha d e f ecl e a e
the internet from writing about the topic, but it was written with an
eye toward being canonical. I spike higher with software developers
and other technologists than I do with finance professionals. My
level of expertise with regard to the field of salary negotiation or
career management for software developers is commandingly high.
At the same time, there are many brands that are attempting to
own those and my level of expertise with regard to the overall field
is relativel l . I h gh , Oka , if I la flag a he
intersection of these two fields, I will only be competing against
f lk ha a e al i e e ed i he i e ec i f h e field .
I could verify that with a quick google; in 2012 that was
approxi a el e. Beca e I e aked hi a ke
positioning for myself, when anyone else wants to refer to this
c ce he e g i g efe e beca e I a he i a d
which conversations about engineering salary negotiations will
happen. That has proven to be true over the last eight years.
There is a blessing and a curse to this. This piece is by far, up until
six months ago, the most effective thing I had ever done
professionally. You characterized the economic value to an
engineer over the course of their career of effectively applying the
advice in the piece as being more than a million dollars. That
characterization is accurate. Many people email me to tell me the
results that they got as a result of applying the advice of the piece
and I keep a running tally. The running tally is currently in the
high-single-digit-millions of dollars of additional salary per year, just
from the people who have told me what their results are. If you
assume that for each person who tells me their results there are

338
other people who are getting similar results but not choosing to
di lge he e, b adl e i a e i ha I e achie ed a e-
allocation between capital in the software industry and labor in the
software industry of somewhere on the order of fifty to a hundred
million dollars per year. Most of my software businesses have not
splashed around fifty million dollars a year in the world economy,
but this one thing I wrote in one day in 2012 did. One the one
ha d, g ea , i a e f l e a le me of what directed effort
can achieve if you choose your projects correctly. On the other
hand, in the spirit of candor, there have been years in the 2012 to
2020 i ef a e he e I ha e aid, Da i , hi g ha I did hi
year, nor the set of all things that I did this year combined, created
as much impact as that thing that I wrote back in 2012 did this
ea . I e hi g ha I eflec he ch i g hich
challenges to embark upon and what to write each year.
Why is it important for technical people to understand business
realities?
To use a gross approximation, business is a technical system for
convincing people to do things that are in their interests. As
technologists, we should be extremely interested in technical
systems that convince people to do things that are in their interests.
There are more instrumental reasons to care about how business
hi k ab hi g : i e e el ele a ca ee g al a d
career planning; it will result in you getting more material benefits
out of your career; and it will make it easier to get projects done in
your company because there will typically be business decisions
makers who will be in the critical path for getting stuff done,
particularly as you get more advanced in your career. The
fundamental insight of why business is important to technologists is
that it is a technology like any other one. It is amenable to the
skillsets that you already have and will make you more effective at

339
the other technical skillsets that you have. If you approach it with
he igh i d e , i ac all e hi g ha i e e el f . Tha
is my elevator pitch for it.
I think that technologists have an unfortunate tendency in the
community of ha he ja g putting up an ugh field and
thinking that there is quote-unquote a business guy somewhere who
is going to handle this for them. They believe that they will stay
pure and deal with technical artifacts vis-a-vis other technical teams
for the entirety of their career. I would encourage people to
understand that a) literally everybody has a bit of business in them.
If you are in a conversation with a prospective employer,
c g a la i , e d i g e e i e ale , he he k i
or not. And b) the sort of unilateral disarmament with respect to
talking about things like money and sales and marketing outcomes
and planning processes sets technologists up for cutting a take of
value creation in a way that is unlikely to be cut to their interests.
My biggest professional goal over the course of my career is
maximizing the ability for as many technologists as possible to
create value for themselves and the causes they care about. Given
that, I would encourage everyone to assume that these topics are
within your locus of control, something that you can get good at,
and something that you should feel comfortable doing, because
they are not worthy of some of the scorn that often gets heaped on
them in our community.
Is there anything else that you want to get on the record that will
make this feel like a more complete interview?
You should ask me a question about brand positioning, finding
your niche, and writing repeatedly on a topic.
Sure. How do you use marketing and other forms of positioning to
indicate the value that you and your work provide?

340
I s helpful for people to talk about one level up from individual
iece a ifac ha he e ki g a d c ide ha hei ,
to use a marketing word, brand positioning is over time. Early in
my career, I would write about whatever I was working on that
week, and so my blog was a potpourri of topics. I realized over
time that I had a comparative advantage on a few topics, one of
which was the intersection of engineering and marketing. The
more work I did on the topic both the better each individual piece
got, because I was specializing on that, and the more compounding
advantage was created for my career because I came to be known
as the specialist in the topic that I was indeed specializing in. Each
individual piece I wrote would receive more magnification from my
a die ce, beca e agai i he e e i i g ab he hi g he
a e e hich I k i g i g be i e e i g beca e he
i e ab ff bef e ha a d he effec ball . Y e
exposed to better opportunities, your better opportunities expose
you to other experts, and the other experts expose you to the ability
to deepen your craft, to bounce pieces off of them. All of that
rebounds on your ability to create high-quality output, which
increases your perception of experti e. I a e i c cle. I
a i c cle e abled b ide if i g ha i i ha eg da,
what it is that you enjoy doing, and what it is that you can do in a
fashion that creates value for other people.
One proxy for value created for he e le i : I hi e hi g
ha he ld ill a e d ? I hi k ha c e i i h al e
creation. There are a lot of hobbies in the world that are worth
d i g f a i di id al e ,b i f e ea ie d a h bb
or a cause that is worth doing if you have something that has solved
the money problem for you. I generally tell people to do
e hi g ha l e he e ble a d he d ha e e
he a f he e f hei ca ee . A fi ha ece a il

341
optimizing for a hi g ha ea a d dea hei i e e b i
less commercializable.
From a brand-positioning perspective, I think again technologists
tend to be a little bit skeptical of the idea of having a personal
brand or the words brand positioning. But, if you think of every
technologist you respect and you were to articulate to a friend why
you respect this person, the answer that you are likely to give is a
concrete instantiation of a brand positioning for that person whom
e ec . Wh d e ec J h Ca ack? Well, he
made Doom and did things in the creation of Doom that were feats
f ech ical ge i . A cia i g fea f ech ical ge i ih
someone is a pretty high-quality brand positioning for a
ech l gi . The fac ha e e i ing Doom and not
enterprise software is not essential to how that story is told. There
are similar things that happen up and down the spectrum. There
are folks that intentionally work on optimization problems or
technical scaling, concrete technical things. There are folks that
create their brand positioning through a combination of voice or
taste. 37signals, for example, now called Basecamp that company
is extremely deliberate about how they put themselves out into the
world. Many technologists are less deliberate about and that has
worked out well for them. There are infinite points where you
yourself could be deliberate about how you put yourself out into
the world that would not only advance your own interests but make
the work that you do more effective at achieving its goals.

342
Tracy Osborn
Tracy Osborn is a writer and frequent conference speaker. She has
bli hed h ee b k de he Hell Web e ie : Hello Web
App, Hello Web App Intermediate Concepts, and Hello Web
Design. She is a frequent speaker at numerous events, writes
extensively on her personal website, and currently works at
TinySeed. We spent a lively half-hour discussing her work.
How did you get into technical writing with the Hello Web series
and what inspired you to write the books?
M i e i deg ee i i a a d de ig . Bef e ha , i he 90 , I
started messing around with doing HTML websites. I thought that
I was going to be a programmer, but when I went to university I
tried computer science. I ended up switching my major from
c e cie ce a a I did like he a ha i e i
was teaching programming at the time. I got an art degree and
started working in front-end development doing HTML and CSS,
b I e al a had ha a k f a i g b ild ff. I liked
working on the web and even though I was doing front-end, I
always wanted to move into full web application development. In
addition, I was also working in the bay area, Silicon Valley, so I was
surrounded by a lot of people who were starting start-ups and who
were entrepreneurs themselves.
After working at my jobs for a while, I came to the idea of building
a website for wedding invitation designers. First I went through this
process of trying to find co-founders to code it for me because I
thought that I a ag d ga e .A e i I eali ed
ha ld k a d I eeded lea P h . L g
short, I slowly taught myself Python and the framework Django and
I launched a website that turned into my startup, WeddingLovely.
Once I was successful enough with WeddingLovely and had

343
learned enough about web application development, I looked at
the resources that I had used as well as that experience in university
of learning how to code. I thought that there was a way for me to
build a better tutorial, the kind of thing I wish had existed when I
was just starting out working with Python. I had some availability
a d a ed d a ide jec , ha h i a ed. I h gh I
could do I d a a be e , b I a ed ake a tutorial
to teach people how to program that fit more the brainspace of
people like me who are visual learners, who had experience with
HTML and CSS, and/or who wanted to build web applications
versus learn how to write algorithms.
How did you define your audience? What level did you write for
and what background knowledge did you assume in your books?
I was writing for myself when I was learning. I just aimed my
writing at the kind of person that I was. I was a web designer who
was worried about programmi g a d h gh I c ld be a
programmer. I felt more comfortable with browsers than command
li e . I a ed ee he e l i he b e . Tha h c di g
felt real as opposed to seeing it in a text editor or a command-line
interface. In terms of knowledge, the other thing that I really
wanted to focus on was assuming my readers had no programming
knowledge. There are a lot of tutorials out there that assume that
you know what a Model-View-C lle i , b I did a
define those terms because Hello Web App is really about helping
you build a web application.
The g al a each Dja g ga i g P h it
a li e all he fa e a ge f Id k h d
hi I ha e e hi g I ca la ch He k . M goal was
to get someone to a feeling of success, get them up and out as fast
as possible, while ignoring all of the theory and ignoring all of the

344
backg d a d he h f hi g . M he i a ha ce
someone has something live and they felt successful, that would
he h he hi k, Al igh , c l, I ha e hi eb a lica i
li e, le fig e ha a ie i . Le g i h i Vie ,
M del , Te , ha ki d f ff. S I delibe a el ke h e
terms and that kind of wording out of the book with the idea that
i li e all g i g ake f e e a d ge e le
started faster than trying to throw everything at them at once.
Did you do the same process in reverse with Hello Web Design?
I launched Hello Web App, and the second book, called Hello
Web App Intermediate Concepts, building on the first book that I
wrote. I liked having these beginner books for programming aimed
at designers or front-end developers. I decided to do the other side
of the coin, which was a beginner design book aimed at developers,
i g he a e c ce . I e e, he fa e a h e
sort of success you can get, ignoring a lot of the theory, a lot of the
reasoning behind things, and giving people a really small, easy-to-
pick-up book. I a a f ce beca e hi i e I a
writing for myself I have a degree in design so the fun challenge
was to, like you said before, define the audience that I was going to
write for. What made it easier for me is that I had this thesis of a
kind of person on the Hello Web side, so I had to switch my
focus.
How do you decide that a topic is big enough for a book instead of
an article? How do you scope your books?
I think length is what I go for, but my books are also really small. I
know there are lots of differing ideas about this, but for me
personally, a good article length is 2,000 to 4,000 words. Hello
Web App is 18,000 words and Hello Web Design is 28,000 words,
so compared to some of the big published books, which are

345
probably on the o de f 100,000 d , he e i e a bi h e .
M e i a , I hi e hi g ha i h elli g? I a
making a lot of income at my day job with WeddingLovely, and I
needed to supplement my own income, so I needed to work on
projects that c ld b i g i c e i . I a c bi a i fk i g
that I had just enough to make a book but not too much. I wanted
a short book that would be something that people would want to
buy.
You branched into video with both of these series what was the
process of making those?
Originally with Hello Web App I was just going to write the ebooks
a d a a e back. I a a he fi Kick a e did i cl de
video. Right before I was going to launch it through the Kickstarter
to people who had preordered less than a month before launch I
a eadi g e a icle ab h if e elf-publishing a
book, you should always have video. You can sell the videos for
much more than the book and your overall revenue is going to
increase. That actually held true for me. After launch something
like 70 percent of my orders were for ebooks, but 70 percent of my
revenue came from video. The first round of video I never got any
complaints about this but my first round of video was very rough.
I literally just used my MacBook Pro and regular old headphones,
and I built my web-app and reviewed the book. But, when I saw
how much people liked those videos, I bought a new camera and a
new microphone. I re-recorded everything to make the videos
higher quality once I realized the value of having them.
A lot of the process of writing my first book was trying to figure out
ha I d k a d he lea i g i . I a ed lea a ch
as possible. Even with the video project, I was pretty sure that was
going to pay off in terms of time versus effort versus money. The

346
b f he ide a ha I did k h d c ee ca
and edit them and make a proper video, so I decided to learn how
d ha . I e c a chi g a i ch a d lea i g ha el e I ca
do.
Why did you decide to teach Django in your books?
F eb a de el e , I a h ge fa f Dja g , e eciall f
beginners. There are several reasons for this. Django is built on
Python, and I think Python is the easiest programming language for
a beginner to pick up because of its simple syntax; it looks like
E gli h he e ii gi . Dja g , fP h ,
abstracts a lot of things away. Again my goal with Hello Web App
a ha e a l fi ci a dal f he . I did a
to explain what the nitty-gritty of a database, I just wanted to say in
he b k, He , he da a a e bei g ed. Thi i f ai i
c i gi he eb a a d i bei g ed e he e. Tha
the level of information I was working with. I like Django because it
has everything built-i a d d e e i eal f e .S I
could, like I said before, get people from zero to one as fast as
possible.
There are other frameworks on Python like Flask, which are really,
really great, but I would consider those kind of level two or level
h ee ial lea i g jec . Whe e lea i g eb a
de el e i h P h , i eall ef l a i h Dja g .
La b lea , I did e i ha I l e he Dja g
community. I think that out of all of the programming
communities, it is the most friendly to beginners. There are lots of
beginner events including Django Girls running workshops all
over the US and Europe. The Django conferences are beginner-
friendly and encourage beginners. I like Django not only for the
fact that it has all of the bits included, but also because I know that

347
if I g i g b i g a e ga e i ac i , hi
community is going to support them.
How does creating a video or article compare to creating a
conference talk?
C fe e ce alk , f e, a e elli g. I e d e i e a l f
conference speaking not so much the last year or so, but there
were a couple of years where I was at 15 or 17 events a year. There
are two different kinds of conference alk . The e a c fe e ce
talk and a conference keynote. The keynote is more storytelling.
The e g i g be ea f ac al ake-aways from a
ke e, b la gel e he e i i e e le, ge he h ed
for the conference, get them emotionally involved. Conference
talks or panel discussions have to have this fine balance of
storytelling with a lot of take-aways, but also in a format that is
really down to earth and friendly, at least for my kind of talks.
Articles are even more formal. My writing in general is pretty
friendly and pretty irreverent I guess, but I try to be the most
serious in an article or book. I try to turn that down a little bit for a
conference talk and lean into being a human onstage.
What was the process of establishing that tone and finding your
voice in writing?
My university professors would probably all say that I was an awful,
a f l ie .I f ha I e i e a d elf-published three
b k fa . The fi b k ac all a edi ed b a
professional. I ended up leaning on the Kickstarter community and
backers that I had. A lot of people who were very into writing and
grammar, often without me asking, would nitpick, which was great.

348
I a e ible e i i e at university, papers were my nemesis
and my grammar is atrocious. On the one hand, I like to read
friendlier down-to-ea h i i g, a d I k ha ha I a . O
he he ha d, i e hi g ha i ea ie f e iea
e e h d e like i e. I a li le bi f a c ch but it
k ell f ha I i g d .W ii gi
strongest skill I e f a a /c ea i / i al e f e .
Tech ical c e i f . I feel like i eall ii g
sometimes. One of my conference talks was talking about technical
writing and trying to encourage people to write more in a down-to-
ea h, f ie dl a e , like I e bee alki g hi h e call.
Tha h I a ha d ha e feel like ea ie i
order to get information across. One thing that really helps me is to
visualize sitting next to someone and talking them through
something, and then I write it that way.
You said you had a print book at some time, what the process of
creating that?
Righ I f c ie f all f b k , because I started a
e j b ab a ea ag a d I d ha e he i e kee ih
a warehouse. To go back in time, I wanted a print book because I
like ha e e hi g i ha d. I a l ea ie c ea e a
digital book; the process of creating a print book was way more
involved than I expected even though I have the background in
editorial design through my art degree. A lot of producing the print
book was to scratch my itch to figure out how it would work, to try
to learn new skills. I did printing with Print Ninja he e i e
i Chi a b he ha e a US ffice. The e a e e.
It was complicated to figure out who would be the right printer to
work with and how I would ship the books in an efficient manner. I
started out shipping the books that I got back from Print Ninja

349
myself from home. I lived in California. When I moved to Canada,
I had to move over to using a warehouse in the US. This
significantly raised my costs, which is one of the reasons why I
d ha e a i b k igh . It was a very, very long and
involved process, but the end result of having a printed book, and
something that I think looks really good and let me exercise my art
deg ee, a all hi.I g ea ha I ca g ee
and conferences and say, He , he e e hi g ha I e a d
pull out a physical copy. People are excited. They want to buy it
a da k e ig i ., I ch a f e e ie ce a d e hi g
d eall ge i h digi al ide eb k li e a icle .
Print books are a labor of love and a lot of work and pretty
e e i e, b I e ha ha I had i b k . I ill e ck
soon.
What are your tips for promoting your work as a writer?
Conference speaking was probably one of the best things I did for
promoting my books. It was good because I was able to continue to
work on my voice. I was able to travel, which was really awesome,
by speaking at these conferences. I was able to test out my material.
Some material that is in the books was actually tested as conference
talks first. I gave a talk at about ten or so conferences before I
actually started writing the book.
Getting on stage was really terrifying for me because I actually
suffer from no small amount of social anxiety, something that is
significantly bette ha I ed eaki g age. The
initial few times I spoke on stage were absolutely terrifying and very
much out of my comfort zone. It was such a great way to share the
ff ha I d d e, b i g he b k c fe e ce , alk
people i e ,a d e a e ial ha I glad ha I hed
through my fear to become a conference speaker. That also allows

350
 e ge i l ed i c i ie . I e i l ed i he Dja g
community, and their support is one of the reasons why Hello
Web App did so well. For me, being involved with the community
and being a part of all of these conferences has probably been the
number one thing for me for sharing and promoting my book.

351
Daniel Vassallo
Daniel Vassallo worked at AWS for eight years. After quitting to
work for himself, one of the first things he created was The Good
Parts of AWS* with Josh Pschorr. The book consists of two parts:
a section providing an overview of key AWS services and a
complete tutorial on configuring a production-ready deployment
environment. He shared his experience writing the book and his
thoughts on promoting your work through Twitter and other
channels.
What about your background prepared you to write a technical
book?
I will admit this was literally an experiment I did k ha
e ec . I did ha e e big a bi i a ic la de i e ie
a book. I left Amazon about a year ago, I started a business, and I
am living off of my savings. I was trying to figure out different
potential income streams because I was working for myself. The
book idea I d k e ac l h i ca e ab . I hi k I
have seen another self- bli hed b k. I h gh , C ld I d
e hi g like hi ? F a hile I h gh ab ic a d I
mentioned this on the [Writer on the Side] podcast as well. Then
the inspiration came from a tweet that went a bit viral. AWS made
it to the short list of candidate topics for this type of technical book.
For me, the motivation was almost all financial I was curious to see
and I had no idea if I would sell zero or a hundred or a thousand
copies. I had no clue at all it was completely new to me. I was
trying to validate that as much as possible: can I sell this? In this
spirit, another thing I did was to find topics that would fit in a time
b fa h f k. Tha ha I a illi g i e , a d
that was another one of the filters that I had to apply: the sort of

352
 hi g ha ld be e lab i de c ibe did ake he
cut.
When you were at Amazon did you write documentation? Do you
have a strong background in writing from college? Are there any
other sources of your experience?
I used to write a lot at Amazon i a e i i g-heavy company.
Pretty much all communication gets done in writing; there are very
few presentations and meetings, and documents tend to be
significantly preferred. Nevertheless, I think probably what I took
from Amazon in terms of writing skills was a skill for concision.
When I entered Amazon, I used to spell out all of the details and
everything. I think I got a sense of better reducing and eliminating
de ail ha d eall a e ha dil e he c e . I ld
say I have a particular background or skills in writing, from college
or elsewhere.
I wrote a self- bli hed b k. I li e all a PDF that I uploaded to
G ad a d ade a ailable li e. The e a li le bi f cha
i i , hich lie i ha i a li hed i e f la g age,
style, and things like that as a professionally edited book by a top
bli he . I ld a his approach adds value, but it definitely
d e ee h . Agai , hi i he e f b k lea e
b k helf. I j a e cha ge f i f ai ih
c e . I a if I did a e-to-one session with someone I
exchange everything I knew about the topic, but I just do it at scale.
Ba icall , ha I ge i g i ha I d hi k eed e
well honed skills in writing for this type of book that I made.
Ob i l , I hi k i i a ha e a g d le ha he
message ge h gh. O he i e e le like i , he
recommend it, and they might leave bad reviews or ask for refunds.
Id hi k elf-published books have the burden or type of

353
quality that traditional publishers tend to request in terms of style in
particular.
In your writing process, what resources did you consult?
I think my main influence was another book like mine, written by a
guy named Adam Wathan. I had purchased one of his books
about a year ago, a technical book. I like that he jumped straight to
he i . I like he e e he b k a d he e
acknowledgements, about the author, lots of filler, bibliography, all
ha he ff. The e he c e , able f c e , a d he fi
page is just information and it ends on the last page with the last
piece of content. I liked that style and I tried to do something
similar. I actually had a couple of customers that commented that
the book ended a bit abruptly because the last page of the book is
just the last page of one of the cha e . Tha i , he e a e
he hi g . I hi k i bala ce, i ef e hi g. Thi i he ki d f
book you read in a single sitting, probably in a couple of hours.
You can do this from your phone during a lunch break or
something like that. I intentionally wanted that kind of value.
In terms of resources, the only thing I used for basic proofreading
was a service called Wordy where a group of freelance copyeditors
do basic grammar and style corrections. You send them a Word
doc and they annotate suggestions and things that might not be
clea . I babl a ic l ece a . I d hi k ale
e ie ld ha e ffe ed if I did d hi , b I hi k if
can afford it (it cost about $400 in total), it adds a bit more
confidence that e e di g a hi g i h e ba a i g
typos or things like that. Another pair of eyes will reveal things that
might not be clear.
You worked with a co-author on your book, what was that like?

354
It was good. It was part of the experiment. My co-author happened
to follow a similar path to mine. He used to work at Amazon and
left a few months after I left. We went for a coffee one day we
were brainstorming what we could do together. I had been thinking
about the book, I suggested it, and we decided to try it together. I
think I probably could have written the book myself, and my co-
a h c ld ha e hi elf, b a he begi i g e did k
whether it would sell so working together cut our writing time by
half. This way was a bit more fun as well. I ice c llab a e
with someone, especially for something like this that was new to
both of us.
We started working on it in the beginning of October [2019] and
for the first couple of months we were just meeting at a coffee shop
for a few hours each time and drafting together. As the weeks
passed, we tried to formulate it a bit more, and just before the
launch we spent a ten-day stretch where we split the work between
us and we just worked. There were ten full-time days where we
swept it all up. I think in total we spent the equivalent of about
twenty full-time days each on the book, the first ten days were a few
hours at a time in the coffee shop and the last ten days were of
eight hours each.
How did you scope the book? How did you determine what the
g d a f AWS a e?
The main filter that I wanted to apply was that I only wanted to
write about things that I was very intimately familiar with. AWS is a
vast topic meaning there are hundreds of services including lots of
hi g I e e e ed elf. Ba icall , I did ant to do any
research or experimentation. I wanted something that could pretty
much write itself, something that was basically a brain dump of
things that I knew intimately, where I knew what I wanted to say. In

355
the introduction we mentioned that we only talk about things that
we have significant first-hand experience with. That was the first
cut.
The he e e e a fe he hi g ha did ake i . I icall
one of the products that my co-author and I worked on ourselves
he a AWS, e did i cl de in the book. It was part of the
time-boxing process. We tried to group things that were related.
The ec d hi g i ha e lef hi g ha did ela e
together. The theme was infrastructure-related topics; there were
other things like application monitoring and things like that which
we could have included we have first-hand experience with these
things but they would have made the book significantly bigger and
would have taken longer to do. To be honest, we thought that it
might be a good candidate for a sequel, a part two on a different
topic set.
I f , ac all . We a ed i h e hi g a bi le a bi i
to be honest. In our heads it was going to be an even shorter book,
and then we were thinking of creating a book and a series of
screencasts. This was again a business decision more than anything.
With Ebooks there is a bit of price anchoring people are reluctant
a e ha a be 50 d lla , le a , f a Eb k. I hi k
if you offer something that is more like a video course or
something like that the anchor goes away a little bit. Initially, we
were thinking of doing a short Ebook, maybe fifty pages, and a
video course. But, as we were thinking about that, we realized that
it would take quite a bit of time to do the screencasts a e had
done it before so we just converted everything into the book.
Then, in those last ten days when we were focusing full-time on the
book, there were topics that we decided we could get away with
dropping. It would have taken a long time to do those topics

356
properly, especially because we were explaining that the book was
j a elec i f he i a a . I be e ha e half f a
book than a half-baked b k if k ha I ea ; i be e
cover half the topics but be well-written and well rounded rather
than mention things but not elaborate on them enough.
How did you decide how to order the contents?
I a b de f i a ce, f, b i a e hi g ha
we talked too much about. It just felt right. I think the first topics
are the most important parts. We swapped chapters around a little
bit he e i ch f a e e ce b e hi g ligh l f ll
each other. We did our best to put the most interesting and
important parts in the beginning.
Is there anything that was easier than you expected in the writing
process? Anything that was harder?
This book was intentionally supposed to be a summary and
aggregation of information, to condense as much information as
possible. The book is split in two parts, a high-level overview in the
first part and a technical guide in the second part. For the first part,
I originally thought that I would end up with a few more pages.
Agai , I did a i e ff ga h e he
nonsense just to fill in the pages. To be honest I was a little bit
concerned about the psychological aspects I was trying to target
fifty pages, but it was looking like it would be thirty-five and it
ended up being thirty-seven. This is psychological, on pricing: if
somebody pays thirty-eight dollars, how much content would they
expect? There was a bit of uncertainty about this. You wonder
whether people are expecting more, especially as I took preorders
a d I e i ed ha he fi a ld be fif age . I c ld
get to that fifty- age a k i h i la i g he idea ha I ld
write useless things. That was a bit of a dilemma.

357
I a i hi g, b ge e a i g he diffe e f a a d li g
and things like that was easier than I expected. I thought it would
be a bit more complicated to get it to work well on the phone or on
a laptop. It turns out that lots of people have done this before, and
there are quite a few resources out there to make it work.
Can you talk me through the process of scoping and creating your
code samples?
We decided that one of the most daunting things with AWS
somewhere that we could provide value is that you create an AWS
acc a d he i e ha d fig e h d hi g
properly. The official documentation is very advanced with lots of
de ail . The e i gle e i j f ll . We c ea ed a
very detailed tutorial where the final result was a production-ready
setup. We worked backwards from there; we had the final results
and then we spent some time thinking about the right checkpoints
to create chapters that made sense and to not dump everything on
the reader at once. We thought about how to make it not too
daunting by breaking it up into small pieces so that the reader
ld feel like, Oka , I a i gf c a ch. I c ea e a e
account, make something where you can see it and improve it a bit
and improve i a bi a d c i e like ha . The e a e
creativity there in trying to break it up in a way that makes the most
sense, and the code samples were created by just working
backwards from the final result that we already had.
For your company Userbase, are you preparing any kind of
content strategy?
P e iall . Righ ,i e ea l age . I a b a ed
b i e . I ha e ake i e e a hi g like ha , a d I
d ha e he e e g fa . I j ggli g a fe hi g a
well with it so I have somebody else helping me. I think the

358
marketing for both me and Userbase so far has been sharing
lessons. I try to show the behind-the- ce e f he b i e . Tha
been working well so far again I attribute pretty much all of the
success of the book to the audience that I built around these things,
mostly on Twitter.
I he a e hi g i h U e ba e. I j la ched h ee eek ag ,
and I got a decent following as well about a thousand people on
Twitter on the Userbase account, a few people following on the
GitHub site, a few thousand signing up for the service on the free
ial. I e ec c i e j each a d ha e. Whe he ha
going to be in blog posts, tweets, or a mix or tutorials or whatever is
unclear. But definitely i he e f a ke i g ha I e ec be
doing rather than spending money on paid ads or any other things.
I a big fa f e ha i i g ea ch e gi e i i ai
anything like that. I prefer organic word-of-mouth reach that
works well for me in terms of getting attention, getting people to
ee ha I c ea i g. Th e ha like i a e i e e ed f ll a d
subscribe and tell their friends or followers about it.
For the book, the tweet where I officially launched it got four
hundred thousand impressions, which was all word of mouth.
People were tweeting and liking it and referring it to their friends
a d hi g like ha . E e ha I i gi
agg e i el a e, I ill ge a a e age f eigh de a da . I
really hard to de a d he e he e c i g f .G ad
gi e e he efe al, b ei e i d e ge he i f ai
a d he e a e l f bla k efe al . I ec ha j f he
e f he la ch. I f e le h hea d ab he
book a couple of months ago, then either they remember it or
e e ec e d i . Tha ha I e ec d f U e ba e
as well: get attention to it by teaching, sharing, providing interesting
de ail ab h i ki g behi d he ce e , b i e de ail ,

359
lessons learned and things like that. I respond when people ask
questions I engage.
What is your strategy on Twitter?
The value of Twitter is mostly to share a journey as it is happening.
I hi k i a e diffe e e f elli g ha he e
writing a blog post, which tends to be a retrospective. The typical
bl g i Thi Yea i Re ie ; e e d fall i l f
hindsight bias. I think the magic of Twitter, what makes it work, is
that for both the writer and the consumer you are sharing as it
happens. This is a habit I formed: pretty much every day close to
he e d f he da i T i e i e. I eflec ha
happened that day and think of things that my audience might find
interesting, and I share them. I think they like following something
as it is happening if it has some interesting aspects to it.
It works for getting attention. There are lots of inefficiencies lots
of people that follow me miss the Tweets that I send. Sometimes
you have to repeat yourself and sometimes they never see them.
I a effec i e a a bl g i h a RSS feed ha e le ca
b c ibe . O he he ide, i le b de ef e a he
producer of the content as well as for the reader. People are
i i g hile he e i i g he b and just seeing things
he e ig ifica l le f ic i . I he a e f e; i i g a bl g
post takes hours, while a tweet takes minutes. Sometimes the
i i a i c e he I alki g e e like h i
asking a question. If I like how I answer it that inspires me to
summarize my thoughts, which just takes a couple of minutes.
I e f he f el, I d e ac l k ha ca e f ll e
to grow. Some tweets go a bit viral, and they end up bringing with
them new followers, which cause ike . I d i e i all
for viral tweets l I j ha i g i h e ec a i . I

360
trying to imagine what my audience would find interesting.
Occa i all , i e ha d de a d h , e hi g ge a bi
more attention than others, and then there are spikes where I get
eigh h d ed e f ll e . Whe ea da I l addi g
e fif ee e f ll e . The e l f a d e a d i i g
and other aspects ei e e j l ck a d e e iha
high follower count e ee , he hi g ha ca
c l ha e . Tha h a eg ha bee l j
keep it simple not to over-optimize it, just to share. I try to not
share things with my audience unless I think they would find it
interesting. I d ha e a l f e al ff; I e d kee i
around business, technical stuff, risk taking, the behind-the-scenes
f he b i e . I ha d beca e d eall k he
audience. I have almost twenty thousand followers. Obviously, I
d know what all twenty thousand people like to see, so I have
to guess and understand from their comments.
It took me a while to understand this, in the beginning I was
thinking that my approach would be to write a blog post and then
just link to it on Twitter, just sort of use it as an RSS feed. I think
he bea f i i de c ibi g hi g a he e ha e i g. The
creative part is in managing to make it concise, this art of keeping
all of the important stuff in 280 characters. With practice you get
better a i . B , d ge e g, i like I i i i g
ch f hi . Like e e hi g, ac ice ake be e . I e
been doing this almost every day for a year you start to get the
hang of it at some point.

361
Cassidy Williams
Cassidy Williams has spent years working in developer evangelism,
speaking at dozens of conferences, and writing technical content,
including the Stack Overflow newsletter. At the time of the
interview, she taught with React Training, she now works at Netlify.
She publishes a weekly newsletter, rendezvous with cassidoo. I
interviewed her shortly after her return from a speaking
engagement.
The e f hi i e ie i ha I d like ge a
understanding of your philosophy or pedagogy for teaching
ga i g. I d l e to hear your initial thoughts.
Fi f all, i f , a d I hi k i he be a lea . Lea i g
by teaching is great because you have to put yourself in the mind of
a learner. A topic that you might think that you know a lot about,
you find out tha d , he ac all a eachi g i a d
answering questions for people and trying to cover all of the
different use cases and misunderstandings that someone might
have. You start to learn a topic so much more deeply than you
would have if you were just learning it on your own. I like teaching,
not only to interact with the dev community, but also just because
i a g ea a lea .
You teach in a lot of different ways. Starting with conference
speaking I saw on Twitter that you do live coding. I like public
eaki g, b ha d e if i g. Wha he ce f i g
together something like that?
I love doing live coding talks, mostly because everyone is like,
ha e if i g, j like j aid. I a f a he
audie ce. Wha f ab li e c di g i ha i a g ea a
really illustrate a concept and say you can do this too. Look, if I can

362
do this in front of a giant crowd of people, clearly you can do this
from the comfort of your own home. That really drives that kind of
i h e. Whe I e a i g f a alk like ha I c e
with some kind of idea for what I want to live code, then I build
ha jec b elf. O ce I e b il he jec , bef e he
conference I figure out all of the issues I might run into. Then I
start taking pieces away. I have the final version of the project, the
i i ial e i , ha a he I age I ca a , Thi i
ha I ha e. Le a i j ba e CSS le I g i g i e
JavaScript that uses those styles to make a user interface or
something.
O e f he he alk ha I e gi e e e al i e , b i diffe e
every time, is making art with CSS. I love giving a talk like that
because it gives an artsy angle to writing styling code. Because I
have a lo f e e ie ce i i i g a CSS, I ll gi e he a die ce
diffe e de ig i a d I ll a , Oka , hiche e e
ick I g i g li e c de i f f igh . Wi h ha I
d e a ea ch beca e I k ha I d i g,
my own horn. I think live coding talks are really, really fun because
it makes things seem more accessible and takes away the scariness
of putting something together for the first time.
Do you write and publish a lot of articles too, or mostly focused on
speaking?
I do write articles. I have a personal newsletter, and in that personal
newsletter it has links of the week, the latest trends in web
development, and a section of things that interested me that week.
Tha e e bl g-like. The newsletter also has an interview
question of the week where people can practice their interview
e i a d he I h l i f he e i eek
e i . I al i e he e le e f S ack O e fl , a d ha

363
just kind of a side gig of mine. Be ee h e , ha he e
most of my writing is. I also write articles for occasional blogs and
aga i e a d ff, b ha ki d f a ad-hoc basis.
In your newsletter, you have a compelling and unique voice. What
is your process for developing a strong voice in writing and
differentiating yourself?
F diffe e ia i g elf i i i g, I hi k i eall j ab
finding your own voice. That comes with practice. I graduated from
Iowa State University. At Iowa State I blogged for the university on
cyclonelife.net. I had to write three or four blogs every week for
them and so it was really just a matter of practice. The more I
wrote for them the more I developed what my tone sounded like
and what my voice sounded like. From there, I wrote blogs for my
companies when I graduated from school and started working, and
I would do my own personal blogs. Several years later I started this
newsletter and by then I kind of just had so much practice writing
blogs that the voice I have comes from many years of just doing it
a dj ac ici g. I hi k ha ha a l f e le a e he i a
d , he e like, Ah, ell, I a bl g, b I d eall ha e a
ice. I eed de el ha ice. I hi k ha j c e i h
putting pen to paper, writing stuff down, and actually writing out
blog posts and developing it over time.
What are some of the advantages of your creative process for
writing?
Unfortunately, the extra ability and time give me more chances to
procrastinate, and I am bad at that. What I like about writing is that
I can reread it over and over again and do my own revisions. My
e le e , hile i he c le hi g i he ld, ake
time. It takes me probably at least two or three hours every single
week to write, just to gather all of the links and to write copy. Once

364
I e i e i,Ig e i h ee i e j ake e e e hi g
looks good. Sometimes I end up re-writing complete sections. For
e, i i g i a g d cha ce e i e a d e fec ha e
writi g a li le e. Whe e a e fec i i i a a a
procrastinator in any way, that might not necessarily be the best
thing, but that is an advantage because you can make sure you write
something that is the highest quality you can.
I have a whole chapter in this book about editing. When you say
you go over your writing a few times, what exactly are you trying to
do? What strategies are you using?
I read aloud or just to myself. My personal writing style is pretty
much as conversational as possible, and I try to write the way I
eak. I a ake e ha i d like I c e i g i h
he eade , ha i d like e hi g I e ci ed ab
something that they might find interesting. If it sounds boring the
way I write it or the way I speak it, then that means I need to revise
i . Tha edi i g ce make the writing sound interesting
and conversational.
How do you scope and structure your technical content? How do
decide ha fi i a alk, a d ha h ld be i cl ded or
ha fi i a a icle a d ha h ld be i cl ded?
This is where my love for live coding comes into play. I used to not
live code as much but I started to realize, especially for technical
audiences, they love to see code and they understand code.
Sometimes articles can be very wordy, and so almost every single
time I start with some kind of introduction, but I get to code as fast
a ible. I hi k, Oka , ha e hi g I ca h
ech icall ? Whe he i be f a alk a bl g , I a ki g
how many code samples can I do. The things that I enjoy writing
and speaking about the most almost always lead to code samples

365
and showing how it actually works. Talking about how interesting
and exciting something is i g ea , a d i a g d sales pitch. But
de d like bei g ld, he like bei g ld. The like lea i g
a d he d like bei g j e e ha c ld b e hi g
use something to make someone else money. They want to be
appealed to as someone who is smart and someone who can see
c de, de a d c de, a d he i e i he el e . Tha ha I
try to do with all of my articles and all of my talks. I try to keep the
ale i ch e a i i a d ge aigh ech ical
content as soon as possible with the actual code.
It sounds like you have a pretty strong understanding of your
audience. How did you develop that understanding of what people
are looking for?
That comes from my developer evangelism experience. When I
graduated from school I went to work for Venmo, which was pretty
small at the time. I had a dual role there where I was both a
software engineer and a developer evangelist. A developer
evangelism role is a combination of engineering and marketing,
he e e a e gi ee a a ke i g ea ea
marketer on the engineering team. The role involves speaking at
conferences, going to hackathons, and participating in meetups to
h de el e , He , e ha e hi API, h ld e i . " M
next job after Venmo was the same thing. I was going to
c fe e ce , hacka h , a d ee a d a i g, He e i hi
c de, he e h e i . I a ale , b de d like bei g
sold to, and so I had to learn a lot of nuances of selling to
developers and understanding developers.
When I speak to devel e I e ha I lea ed. If I bei g
h e , lea i g ha a e ea el beca e I a
de el e elf. I c ld a , Oka , if I bei g alked , if I

366
bei g ld , h ld I a be ld ? I d like ad ,
a dId a t to be told how to do something or that I should
d e hi g b e e h d e k h c de
he el e . Tha h I de el ed ha ice it was through
actual work experience, and then just taking it and running with it
for my own stuff.
What are your thoughts on content accessibility?
Unfortunately, accessibility is often something that you have to tell
e le he h ld d , he i e he ll e e c ide i . I
e hi g ha I f e ha e add i , a i g, Oh, e e g i g
add some aria le i he e, We a hi be acce ible
le a c ee eade a d ee h i l k fa . I a j
reading a thread today where someone had their eyes dilated and
he c ld ead a all f a d he had i c ea e
the font size on everything and not all apps and not all websites
accepted those kinds of changes. Accessibility is a subject that I
think is constantly going to be a conversation and constantly needs
be a c e a i beca e i ece a . E e single person
in the world will face some kind of issue with accessibility at some
point in their lives, whether they believe it or not, and I think that
learning to build for everyone is something that needs to be
emphasized in talks and blog posts, pretty much everywhere we
can.
If I i i g a a icle ab , a , eb de el e i Dja g ,
a d he a ig e d e e e ha I i cl de a i f ai
to do with accessibility, how can I put accessibility into that article
in a way that supports the main point and is going to spread these
best practices?
D lea e i a a af e h gh a d d j highligh i like,
N ,d f ge acce ibili he e h e eg i g d i.

367
Doing it that way is not the right way. Accessibility needs to be
ali ed: Make e ha if e g i g c ea e a i age ag,
you always need to have some kind of alt attribute so someone can
h e e i a c ee eade ca de a d i . W i e i a if i
a normal, necessary thing so that way it normalizes it for everyone.
The hope is that the effect will be that more and more blog posts
will do that same thing writers always add in accessibility as a best
practice.
I d hi k ha da , i a ch be e c e a i ha i ed
be. People are very empathetic now, or at least more vocally
empathetic now, and are focusing a lot more on accessibility than
they were even five years ago. I gave my first accessibility talk about
fi e ea ag , a d i a he el hi g. I d k if i
was just the conference that I was at or what, but I remember I was
talking about all of these aria roles and making sure color contrast
is good and application development is able to be adjustable for
any kind of user and nobody in the audience had ever heard any of
these subjects before. Now, luckily, whenever I go to an event it
ee like he e al a a lea e alk ha g e e
acce ibili . I bec i g a e eg la c e a i a d i
such an important one to be having. There are always
improvements in those technologies and one of the things that my
company does is work on an open-source library called reQI. It is
one hundred percent accessible and verified accessible
c e f Reac . We e h i g e a d i he
frameworks as well. I ch a big hi g i c a al a
ha e acce ible c e a d ha e f he ea ha I
work here.
As developers, we write these articles and blog posts to educate
each other on computer science. One thing that I absolutely love

368
that you make are those short Twitter videos. Could talk about
what inspired you to make humor content for developers?
Whe I fi a ed aki g ide , i a j ake j ke . I e
always loved making jokes, but I just kept them to occasional tweets
or a g f ie d . The I h gh , I hi k hi ide bjec i
f , I ll d i . I d l aded a ide edi i g a a d I f d
i a f . S I decided, I ll h i T i e , The i g
really popular. The next week I thought of another joke I could
make in a video, and people really liked it. I kept doing it after that.
I e l bee aki g he e ki d f ill de ide i ce hi a
e . E e i gle i e I ake e I de , I hi he e
e le like beca e i d b? B people consistently
ee like he . I de el ed i a f e al b a d
, hich I eall like beca e I e al a bee aki g he e
j ke . I j ha e bee blic ab he . I f be able
share these jokes and pitfalls and fun things that a lot of developers
face. A l f de a e e d e le a d he d a d
show that they struggle as much as they do.
That sounds like a lot of pressure.
Tha e. Thi h I e bee a eli g ch f k this
is my third week straight of travel a d I ha e bee able ake
a a ide . Pe le ill e age e a d a , He , a e
ka ? Whe he e ide c i g ? The I hi ki g,
Oh da g i , g a c e ih e hi g! S he e ca be
pressure. I also have so many jokes that I want to tell and a list of
he , i j a a e f aki g he ide . S e e le ha e
mentioned making a YouTube channel, but that is a whole other
set of tasks. At least with a silly tech video I can just make it on my
phone and not have to worry about editing and sound, or anything
like that.

369
You said you have a list of jokes ready, do you keep a list of
technical content in general that you want to create and how do you
create and filter that list?
I have a note-taking app on my phone and I have a category in
he e called idea . S e i e i jec idea , e i e i bl g
idea , a d e i e i j ke idea , b e e i gle i e I hi k f
one on the fly, I try to write it down. Sometimes it will end up
being a stupid idea that I never follow through on. Sometimes if
I ha i g e ki d f b ai fa I l k h gh idea a d
hi k, Oh, eah, I c ld b ild ha e a d he ihi. I
write down pretty much every idea I can think of whenever I have
i . S e i e i ill be he I ab I a la e a d
e hi g ill c e i d a d I hi k, O h, I a
e e be hi la e , I igh ake e e la e , b he fact
ha I e i e i d j ki d f lidifie he idea i i d
and helps me keep that going. I have some physical notebooks too
he e I ll ei e j d a a idea. S e i e if I d
know how to describe an idea in words, I can describe it by
drawing it.
I he e a hi g el e d like ge he ec d bef e e e
done?
Thi i g i g d chee , b he e hi e ha I ed
have on my wall growing up and I always refer back to it when it
comes to making content, making talks, making any kind of thing.
I a Helle Kelle e: O e ca e e c e c ee he
e feel a i le a . Id f ll ha . If ha e a
idea, if you have even an inkling of trying to create content, trying
to do a talk, i g i e a bl g , e e if e e if
i he igh hi g d if e ca able, j d i . The
hi g ha ha e i i fi a d e le gi e feedback

370
a d i a lea i g e e ie ce. The e a e a jec ha I e
a ed a d I hi k, Whe ! I e e g i g hi agai . A d
he e a e a he e I hi k, W , if I did ake hi i k, if
I did a e hi i ,I ld ha e g e he e
Ia da . If ha e he i l e d i,j d i.D
worry about negative feedback or anything like that just accept it
and learn from it.

371
Appendix B: The 9 Questions Worksheet
Print these three pages and answer the questions by hand.

Question 1: What programming languages do you know well

enough to write about?

Question 2: What frameworks and libraries within those languages

do you enjoy using?

Question 3: What company-specific technologies do you know

well?

372
Question 4: Which topic domains are you interested in?

Question 5: Who are your clients and what topic domains are they
interested in?

Question 6: Who would you like to land as clients and what topic
domains are they interested in?

373
Question 7: What relevant prior projects have you done?

Question 8: What real-world systems have you studied and could

reverse engineer?

Question 9: What environments have you programmed in?

374
Appendix C: Sources
Chapter 2
O W i i g, S e he Ki g,
https://en.wikipedia.org/wiki/On_Writing:_A_Memoir_of_the
_Craft
W i i g A S a hi g A icle, Rachel A d e ,
https://www.smashingmagazine.com/write-for-us/
Chapter 3
M eI f ai Fai U e, U.S. C igh Office,
https://www.copyright.gov/fair-use/more-info.html
Fai U e, Rich S i ,
https://fairuse.stanford.edu/overview/fair-use/
Chapter 5
Q e: W i i g i hi ki g. T i e ell i hi k clea l .
Tha h i ha d., Da id McC ll gh,
https://www.goodreads.com/quotes/9338856-writing-is-
thinking-to-write-well-is-to-think-clearly
Lea i g Tech ical W i i g U i g he E gi ee i g Me h d,
Norman Ramsey, https://www.cs.tufts.edu/~nr/pubs/learn.pdf
Chapter 6
Lea i g Tech ical W i i g U i g he E gi ee i g Me h d,
Norman Ramsey, https://www.cs.tufts.edu/~nr/pubs/learn.pdf
Chapter 7
Ab W d e , W d e ,
https://wordpress.org/about/

375
 Ab Gh , Gh , https://ghost.org/about/
Chapter 12
F eela ce W i e C ac , Digi al Ocea ,
https://www.digitalocean.com/legal/freelance-writers-contract/
Ne D, Wiki edia, https://en.wikipedia.org/wiki/Net_D
Chapter 13
C igh Ha db k, The: Wha E e W i e Need
K Thi ee h Edi i , S e he Fi h a ,
https://store.nolo.com/products/the-copyright-handbook-
coha.html
Chapter 14
G gle Ad e e, G gle,
https://www.google.com/adsense/start/
Ca b , B SellAd , https://www.carbonads.net
C deF d, Gi C i , https://codefund.io
Sc ch.i i j i i g Digi alOcea , Ti Fall ,
https://blog.digitalocean.com/scotch-io-is-joining-digitalocean/
A cia e P g a S a da d Fee Sched le, A a ,
https://affiliate-
program.amazon.com/help/node/topic/GRXPHT8U84RAY
DXZ
Ab biddi g i e i , G gle,
https://support.google.com/google-ads/answer/2630842?hl=en
Chapter 15

376
 H D De el e P e O e S ce P jec ?,
Hudson Borges, Marco Tulio Valente,
https://arxiv.org/abs/1908.04219
H ge 30,000 Hacke Ne ii eb i e,
Marketing Examples,
https://marketingexamples.com/content/drive-traffic-from-
hacker-news
Hacke Ne FAQ, Y Combinator,
https://news.ycombinator.com/newsfaq.html
Hacke Ne G ideli e , Y C bi a ,
https://news.ycombinator.com/newsguidelines.html
Chapter 16
W i i g a Tech ical B k, A d Le a d,
https://andyleonard.blog/2018/08/writing-a-technical-book/
W i i g a Tech ical B k f Ma i g, Ba P llard,
https://www.tunetheweb.com/blog/writing-a-technical-book-
for-manning/
S Y Wa T W i e a I f ec B k?, Ch i Sa de ,
https://chrissanders.org/2014/02/so-you-want-to-write-infosec-
book/

377
Acknowledgements
First and foremost, I would like to thank my mother, Robin
Bourjaily, for thorough developmental editing and proofreading.
Also, my thanks to my sister, Laura Kiely, for her assistance with
coordinating the beta read and reviewing the manuscript.
Thank you to Bogdan Abaev, Arun Chinalapati, Elana Gibson,
Richard Greenbaum, Willem Junker, PMG, Griffin Mareske,
Alexander Mohn, Liam Niehus-Staab, John Osler, Taylor Price,
Samuel Rebelsky, Ryan Sheridan, Joel Tibbetts, and Eddy Varela
for providing comments in the beta reading stage.
My thanks to Courtland Allen, Jeff Atwood, Chris on Code, Peter
Cooper, Angel Guarisma, Matt Levine, Mark McGranaghan,
Patrick McKenzie, Tracy Osborn, Daniel Vassallo, and Cassidy
Williams for their interviews.
Thank you to Amelia Darling for the cover art.

Legal
Copyright © 2020 Philip Kiely, Philip Kiely & Company
All rights reserved. No part of this document can be copied or
distributed except where permitted by the applicable copyright
statutes, the purchase of an appropriate license, or in writing by
Philip Kiely.
ISBN: 978-1-7350564-0-1

378