A. Jesse Jiryu Davis – Write an Excellent Programming Blog – PyCon 2016

A. Jesse Jiryu Davis – Write an Excellent Programming Blog – PyCon 2016


A. Jesse Jiryu Davis talking to us
about how to write an excellent programming blog. Please welcome Jesse to the stage. [Applause] Thank you. I really love being at PyCon
because the open source spirit is so alive here. There are so many experts who are inspired
to share their code. But I don’t want you to just share your code. I want you to share your words too. I want you to write an excellent programming
blog. So, if you’re in the room, then,
I probably don’t need to convince you why writing is so important. But nevertheless I want to share with you
my reasons why I think that writing benefits us all. So, the main reason is that you’re a specialist,
right? It’s a characteristic of being a programmer
that we never write exactly the same thing twice. So, we’re all specialists. And you’re the preeminent expert
in whatever it is you do, right? You know how to parse New York City
subway schedules or how to do Python development without an internet connection
or to accommodate a colleague with a disability. Like, there’s something that you know
and I want you to write it so that I can learn from you. Writing about it will also send up a flare
that lets your fellow specialists know what you’re into. And that’s great because it allows you
to share advice, help each other with your specialist problems,
and collaborate at the level, not of submitting pull requests,
but at the level of ideas. It’s a very effective way to contribute
to each other’s projects. But even if nobody ever reads what you write,
writing is still worthwhile because writing is thinking, super-powered. I use this, like, super-powered thinking
when I encounter some problem that I’m worried is just going to be
too hard for me. Like, it’s over my head. For example, a few years ago,
I encountered what looked to me like a bug in Python 2.6 where assigning
to a threadlocal is not thread safe. And that was so mind-blowing to me,
and so terrifyingly complex, that I knew I wouldn’t be able to think it
through without some sort of help. So what I did was, I started writing the story
about how I diagnosed this bug. So I know that I’m violating a couple of rules
of public speaking here by showing you a wall of text… [Speaker clicks tongue] I’m gonna help you with that. [Laughter] So right, so I started writing this story
about how I diagnosed this bug before this story was complete. I didn’t know how it was gonna end. But by writing it down as I went,
getting my hypotheses onto the page, and consolidating my understanding
at every stage, I was able, by the time I reached the end a few days later,
to understand the problem, which was indeed a race condition
in the Python 2.6 threadlocal implementation that causes an intermediate memory leak. I had found an easy workaround
and I had this kind of nice article about this kind of awful bug. So, these are the reasons why I think that
writing benefits us all. But there’s kind of a problem that we all
have. Every time I talk to people about writing,
it seems they complain about writer’s block, about not finding the time
or not being able to get started. And this was true for me as well
until a few years ago when I really changed how I think about writing and my approach
to it. And that change in my approach to writing
was this breakthrough that’s made writing prolific and joyful for me. And I hope that by the end of this talk
you’ll understand where I’m coming from and you’ll be able to have the same
joyful parrot leaping out of something experience that I did, whatever the heck is going on
in that image. So, the agenda for today is why,
and since I think you’re all now convinced, the next stage is gonna be what. What should you write? Who is going to read your writing? When will you find the time to write? And how do you improve your writing? So when I read articles that I really admire,
I notice that they tend to fall into very roughly five categories. And the first of these is stories,
the most basic founding form of human communication. And we know how stories go, right? They start with once upon a time. Once upon a time, there was a Foo. This happened, and then that happened. I learned some important lesson. And that’s the story of Foo. When we write stories about programming,
there always needs to be a moral to the story, some important lesson that you learned. That’s the value that you’re promising your
reader in exchange for reading your story to the
end. Quick show of hands, who here has read
Glyph’s Unyielding? I cannot recommend it enough. It’s famous among the specialty
of Python async people. So once upon a time, Glyph was writing
a text adventure game in multi-threaded Java. And because he was using multi-threading,
he had bugs. And the particular bug that this story’s about
is where there was a feature in the game, a brass cockroach, that players
could have in their inventory. And on a timer, the cockroach
would leap out of your inventory and scuttle around the game world. But due to a concurrency bug,
sometimes it would leave a copy of itself. And this led to an exponential multiplication
of brass cockroaches that filled both the players’ inventories
and the entire game world. Glyph writes that, given that the feeling
that this particular narrative feature was supposed to inspire was eccentric whimsy,
and not existential terror, the non-determinism introduced by threads
was a serious problem. [Laughter] So, the lesson is that explicit async code
with the yield keyword or some other sort of marker is far less prone
to race conditions than multi-threading is. And there’s this appealing and memorable image
to go along with it that makes this one of the most widely cited blog posts
in my little corner of the Python world. So this is the kind of story
that you might want to write. You also might want to write an opinion. And opinions, they’re structured
just like we learned in high school. You state your thesis,
you back it up with evidence, you anticipate likely objections,
and then you conclude by restating your thesis. The important thing here is,
don’t go attacking people. Don’t go saying that stuff is bad, all right? Mr. Miyagi says, karate for defense only. [Laughter] You want to have an interesting
and insightful opinion that is actually productive for people. So a great example of this
is Julia Evans’ “Don’t feel guilty about not contributing
to open source.” Julia noticed that there were periods
when open source software just works for her. She doesn’t need to fix bugs or add features
to anybody else’s project in order to be able to use their code. And for her, she felt guilty
about not making contributions. But then she realized
that it’s when we have our own use cases, our own itches to scratch,
that we make useful contributions. And otherwise, making contributions
out of a sense of guilt or obligation is typically not as useful. So this is an interesting and insightful
and productive opinion that doesn’t hurt anybody’s feelings. Probably the most common kind of article
that we write about programming is, we say how to do something. And the structure here is very simple. You say that doing Foo is important
under the given conditions. I’m going to show you how to do it. You do this, and then you do that. There, now I’ve shown you how to do it. You should go out and do Foo. You begin with a motivation. It’s important under these circumstances. You want your user to know
whether they ought to invest the time in learning how to do Foo right upfront
so that you can make them a promise to fulfill. And this example of a how-to
is Kenneth Reitz’s article about growing open source seeds. So, Kenneth is the author of Requests,
one of the most popular Python projects. And he’s writing about how to maintain and
nurture a very popular project, and be responsive
to users without burning out. He motivates it with an opening anecdote
about a Python project that was open sourced and then abandoned by Facebook. And everybody was mad at them. And so this is the cautionary tale. This is what you don’t want to do. You don’t want to let your users down. And that’s the reason why you want to learn
the how-to that he presents to you. Another thing that we can emulate
in Kenneth’s article, here, it might be a little hard to see,
but notice what he calls this. He doesn’t call this piece of writing a blog
post. He calls it an essay. And I want you to think about what you want
as an article or as an essay. These words connote deeply thought
pieces of writing that have lasting value that stands the test of time and continues
to pay off for your investment for years to come. Whereas a blog post, you know, it’s ephemeral;
it’s here today, it’s gone tomorrow. It’s probably not as worth the time
that you invested into writing it or users’ time reading it. So write essays and articles, not posts. Besides how-to’s, there are also articles
about how things work. I apologize that this is a viper, not a python. [Laughter] It’s the best I could do; forgive me. I think that we all sort of have, like,
a little bit of engineer in us and also a little bit of scientist. And engineers, we want to know how to do things. But scientists don’t need to make things. Scientists just want to know how things work. Curiosity is motivation enough
for the scientist within us. So, an article about how something works,
it can just start off with, do you want to know? If you don’t, don’t read this. If you do, I’m going to show you
how it’s implemented. It does this and it does that. There, now I’ve shown you how it works. A nice example of this is Allison Kaptur’s
article about syntax warnings and symbol tables in
Python. She had a student at the Recurse Center,
which was called the Hacker School then. And the student hit this bug
where doing from a module import star within a function call
would throw this syntax warning. And for the engineering side of us,
we don’t care why this happens because the workaround is simple enough. You just move that import statement
up to the top of the file. But for the scientist part
of Allison’s personality, this wasn’t enough. She needed to know why this was happening. And figuring that out led her to investigate
the Python compiler and how it implements its scoping rules. And explaining this to us,
it satisfies the scientist within us. The final type of article that you could write
is a review. Anytime that you read something, read a book,
finish playing a video game, see a movie, use an application, consider reviewing it. And reviews are a little bit dangerous. So here’s how I recommend you approach them. Say that you read or saw
or played or used something. And describe what it is. Describe the experience that you had reading,
seeing, playing, or using it. You can evaluate,
did it have strengths or weaknesses? And then in conclusion,
tell me what it’s good for, right? So don’t —
this isn’t thumbs up, thumbs down, you liked it, you didn’t like it, four outta five stars on Yelp. Spend most of your time not evaluating the
thing you’re reviewing but analyzing and describing
it. That’s what’s most useful to your readers. I promise this is the last time
I’m gonna toot my own horn. And… [Speaker clicks tongue] Once again I’m gonna prevent you from reading
while I’m talking to you. So I wrote this article about this O’Reilly
book, Building MongoDB Applications with Node and Backbone. And I tried to make my review very useful
to readers of my blog by first describing what was in the book. It was a chapter by chapter example application
built from the ground up using these technologies. I described my experience of reading the book
as somebody who has certain expertise. I know MongoDB well but not Node. I thought that the author
did have some weaknesses. The book had an exception-handling style
that I thought was very dangerous. But the book also had a lot of strengths. It was a very methodical and easy to understand
presentation of an example application. And in conclusion,
if you have the sort of level of expertise that I do, this is a good introduction
to these technologies. So, whenever you review a book or anything
else, this is the kind of review that I think is most useful for your readers. So I promised that somehow I would help you
to overcome writer’s block or help you to overcome your hesitation or your procrastination
about writing. And keeping these five kinds of articles in
mind can really help with that. So let’s say you have a topic,
but you’re not sure how to get started. You can ask yourself,
is your topic best approached as a review or a how-to or an opinion piece? Then you have a template already set out for
you. You just need to fill in the blanks and voilà,
you have an outline. You’re already halfway to writing the article. On the other hand, if you want to write
but you don’t have a specific topic in mind to choose, you can ask yourself,
do you have a story to tell, do you have an opinion to argue for,
do you have something that you want to explain how it works? You can use this to brainstorm topics
and figure out what most inspires you to write about. So who’s gonna read you? How do you find your audience? And right off the bat I’m gonna say
that this is not about search engine optimization. SEO is a set of techniques
for competing with people who are writing about similar topics for a mass audience. And that is the exact opposite
of what we are doing when we write. We are writing articles about our specialty
for an extremely narrow set of readers. So they’ll find us. They subscribe to aggregators like Planet
Python. So, if you’re a Python writer,
somebody who writes about Python, get your blog aggregated by Planet Python. It merges feeds of Python authors
into a single feed that Python people read. And at the end of this talk, I’ll share a
link that will include instructions on how to get your feed included. There are planets for many other specialties. If you write about NoSQL, or data science,
or visualization, get aggregated by their planets too. There’s also all of these weekly emails,
Python Weekly, Pycoder’s Weekly. Their editors are looking for submissions. When you publish an article about something
they’re interested in, send them an email and ask to be included. If you do this basic legwork,
that’s really gonna be enough. You’re writing using the words and phrases
that your fellow specialists are searching for. And Google was made for exactly this. Uh, do not worry; they will find you. How do you improve your writing? I think this is probably why a lot of us
are in this room, right? So writing, like any skill,
it improves with practice. Additionally, you want to read as a writer. And get an editor. So, I practice by bookmarking the articles
by my favorite authors, the articles that I admire most. And when I write an article, I might try
to specifically emulate whatever it was that I thought made that article effective,
either its prose style or some technique of writing that I particularly liked. And I also read the internet
a little bit differently. So as people who care about writing,
let’s promise each other that when we read a relevant article, we’re actually
gonna read it to the end. And that’s gonna distinguish us
from 90% of readers of the internet. And don’t just skim to the end. Actually read the words. And when you get to the end,
just take a moment to ask yourself, was this piece of writing
effective or ineffective? And either way, how could it be improved? And share early drafts with your friends
and ask for their critique. Pretty early on, you’ll discover
that some of your friends just say, great, good job, I’m proud of you. And other friends
will provide insightful critiques. So you want to keep leaning on the latter. And get writing buddies with whom you share
drafts and share criticism. If you, oh right, so I know what’s next,
making time to write. So when are you gonna write? People complain about, they have these blog
posts that they wanna write. But they can’t make the time for it. And I think that this sort of guilt
about having ideas but not writing them down or having a blog that hasn’t been updated
in a while, it comes from a misconception about what we’re doing on the internet. We’re not Buzzfeed. We don’t make money off of writing
and we’re not obliged to come up with a stream of constantly new content. So just write infrequently. Write when you have something to say. Write when you’re inspired by something that,
some discovery you made or something that you achieved that is so exciting
that you just, you cannot help but share it. These are the circumstances under which
you will create articles that have the greatest value to your readers
and which best continue to pay off your investment for years to come. But if you only write infrequently, how are
you going to keep your writing muscles toned? How are you gonna practice? In that case, write short things more often. And reviews are particularly great for this
because there’s always something fresh to write about. You’re finishing a book, whatever it is,
maybe you can make a commitment that whenever you finish a book,
just set aside an hour to write a three-paragraph review of the book. Doesn’t need to be a programming book,
although if it is, reading it with the intent to review will lead you to pay
much closer attention both to its content and its style than you would otherwise. But whatever kind of book it is,
just practice encapsulating your experience of reading the book in a few paragraphs. This will really kind of keep your muscles
in shape. So, by changing how you think about your writing
and by having ideas about the basic structures to choose among, you can become
a much more prolific and much more joyful writer and a much more powerful communicator. And the next level of this is writing together. And no, I do not know what is going on
in this image. [Laughter] Ooh — I, I really don’t. [Laughter intensifies] This year at MongoDB, we created a tech blog
where the programmers who work for MongoDB can write about our discoveries
and our accomplishments and our challenges. And I’ve been editing and writing for the
blog and soliciting articles. So I’ll ask friends to write up some cool
thing that I heard that they were working on. It’s gotten the word out about what we’re
doing. And it’s been a way for me to contribute something
to my company and my colleagues besides writing code. If your company has a tech blog,
you should write for it. And if your company doesn’t have a tech blog
yet, this is an opportunity for you because you can use your passion and skill
as a writer to spread the word about what’s going on at your company
and advance your own career and raise your own profile. Something else I’ve been doing this year
is writing for the PSF blog. And that’s been a total blast
because I stay connected with the community, I interview prominent Python people I admire,
I keep abreast of the PSF news and see how PSF grants are benefiting people. It’s been a way for me to contribute
to the Python ecosystem using words and to connect to people much more effectively
than I had before. So if you’re involved in a nonprofit
or an open source project or a community, think about blogging for and about that community
and spreading the word about what’s going on. That can be a really generous way
for you to contribute back. So, I promised you a link. And here it is, bit.ly/excellent-blog. And this links out to all of the articles
that I showed you today and a dozen other articles that I admire and that you can emulate
to improve your writing. It also has instructions for how to get aggregated
and links to other resources for refining your writing
and becoming a more powerful communicator. So I won’t take questions now,
but I’ll be out in the hallway and I look forward to talking with you
about writing an excellent programming blog. Thank you very much. [Applause]

One thought on “A. Jesse Jiryu Davis – Write an Excellent Programming Blog – PyCon 2016

Leave a Reply

Your email address will not be published. Required fields are marked *