During PyCon, I gave a tutorial on writing about Python. I’ve included my script below. You can also watch the full talk on YouTube, but be aware that it’s over 3 hours long if you don’t skip the exercises.

In this workshop, we’re going to learn how to effectively write ABOUT Python. We’re going to be talking about some general mechanics of writing about technical topics, as well as some Python-specific topics.

• Major pitfalls in Python communication
• Common Python audiences
• Strategies for editing and testing content about Python
• Writing opportunities in the Python community

We’re going to do several exercises to practice these strategies, although they may be a little different than the average workshop exercise at PyCon. We’re going to write prose, not code, so this may be a little different for some of you.

I’d also like to note some specific topics I’m going to cover that can be uncomfortable for some audiences. We’re going to discuss race, gender, ability, and age, along with ways Python community members have been marginalized.

Python Versus Prose

The Python community, as a whole, talks more about communication than many of our counterparts. My personal theory is that Python enjoys a special status in newsrooms. Part of that is Python’s use in data journalism. But I think Django’s development is the big factor: one of the most widely used Python framework came out of a daily paper. 

Python, as a result, is pretty good about documentation. We’ve got decades of good examples to build from, as well as some tools that help us with writing prose as much as they help with writing code.

However, writing code in Python remains a different process than writing prose about Python. One of the biggest differences is in the needs of the audiences for each. The primary audience for Python code is the Python interpreter. Python is a format intended to be readable by machines. We talk about the readability of our code a lot in the Python community — more so than many other programming communities — because we value being able to understand our own code without mechanical intervention. 

We value human-readable code because we, as humans, are responsible for creating and maintaining our code. Our future selves thank us for clear and understandable code: my future self is always happier when my past self makes future maintenance easier. But humans are still a secondary audience for Python code. Beyond an interpreter or a compiler, most human readers of any such code will have at least a passing familiarity with Python. Yes, non-programmers will see the code, but most of the people interacting with it will have a more technical background than the average reader. 

Python’s Pitfalls

Over the course of working on  The Python Style Supplement, I conducted both surveys and interviews about what books, blogs, and other materials members of the Python community read to learn more about the programming language. I also took the opportunity to talk to these folks about what problems they had with Python media — what issues made learning and using Python harder.

There are four issues that I heard and saw over and over again. 

• I’ll be going through a tutorial and it won’t work, because I’m running Python 3 and the tutorial writer used Python 2.7
• The writer basically told me to go read the code
• I keep trying to look up the difference between things like PyPy, PyPi, and PyPA 
• I can’t find anything written about a particular Python project

As writers, we want to avoid these pitfalls.

I’ve rewritten the four pitfalls here so that we can more easily talk about them from a writer’s perspective, instead of a reader’s.

• Telling  readers which versions of Python and other dependencies you’re using
• Creating context for code. Even sample code isn’t self-documenting
• Explaining and disambiguating the jargon that’s accumulated around Python
• Getting resources to promote new writing, especially on open source projects.

We’re going to get much deeper into these pitfalls and how to avoid them over the next few hours.

I’m also going to add one more pitfall, based on my experiences writing about Python. 

• Setting expectations about what Python programmers know at different points in their careers

These are in no particular order, and I’m actually going to start with that last point.

Python Audience

When we’re planning what to write, we need to know who we are writing for. The Python community is not just one giant homogenous whole: even if we limit ourselves to talking about just Python skill levels, we’re still talking about a range starting with folks copy-and-pasting Python scripts without a clue of what they’re doing all the way through to folks who have advanced degrees in computer science.

Writing something useful to every Python programmer on that spectrum is hard — and rare. I’m a professional and I don’t bother most of the time. Instead, I write for smaller sections of that spectrums, sometimes rewriting the same material in different ways to make versions useful different audiences.

Talking about these differences in the abstract is hard. Let’s look at this in a more concrete way.

Python Personas

Here are a few different personas we can find in the Python community. These people are entirely made up, but we can talk about how they would respond to different types of writing.

• Pat the Newer Python Dev
• Piper the Experienced Python Dev 
• Nat the Nonprogrammer
• Ruby the Experienced-in-Another-Language Dev
• Darby the Decision Maker

There are, of course, plenty of other personas we could talk about, but this narrows down the field to a couple of key points. I actually use these personas in writing projects and have gotten to know these folks really well. 

All of my imaginary friends here have back stories.

• Pat is a recent programming bootcamp grad. They’re on the younger side. Pat loves Game of Thrones and will get every reference to that show you can squeeze into an article, but Pat can’t tell you the difference between Monty Python and the Mickey Mouse Club.
• Ruby got started programming when COBOL was the hot new thing and hates all programming languages equally. Ruby reads XKCD and probably knows more about Python’s Easter eggs than Python itself. That’s going to change next weekend when Ruby is going to learn enough Python to pass a programming interview.
• Darby gets to decide on whether to use Python to build new projects for their startup. Darby often has money to spend and has titles like VP of Engineering and CTO on their resume. Darby also loves football — but not American football. Darby doesn’t use the word ‘soccer’ because Darby works with team members all over the world and doesn’t want to confuse them.

I’m deliberately fuzzy about the race and gender of these personas. Personas aren’t a good tool for figuring out how to address gender, race, and other facets of identity. These personas are MY imaginary friends and they’re a product of MY experience. The furthest outside of my own experience I can go is letting Pat be a Game of Thrones fan, even though I’ve only seen a few episodes. Personas are most valuable when looking at work and educational experience. We will be covering strategies to ensure your writing is inclusive later on. 

In the meanwhile, though, let’s talk about some characteristics we can assign to our personas.

Python Community Members

The Python Software Foundation’s survey of Python programmers is one of the best sources of information for personas. For instance, the 2018 survey found that 50 percent of Python programmers also use JavaScript. 

I’m super confident that Piper, our experienced Python developer, is going to be familiar with JavaScript. Even if Piper doesn’t use JavaScript every day, we can assume a basic level of knowledge.

Pat, our newer programmer, might have JavaScript knowledge, but we’re going to want to add extra context and maybe even link to some resources. As it happens, Pat’s bootcamp curriculum was very thorough — but Pat still wants to know why Java has its own scripting language because even the most thorough curriculum is going to have to gloss over naming decisions made when Pat hadn’t yet started kindergarten.

We can make similar assumptions about Piper and Pat’s familiarity with popular frameworks and libraries in the same way. 

These assumptions are as good as the data they’re based on. The PSF’s survey is based on self-reporting, so there are probably some folks it misses. But it’s still significantly better than other surveys of developers because the PSF works hard to get respondents from different backgrounds. In contrast, surveys of insular communities don’t give us particularly useful data. If you rely on Stack Overflow’s developer survey, you’d be working off of the assumption that 11 percent of programmers are women. There’s a gender disparity in programming for sure, but most programming communities are looking at closer to 24 percent women, based off of surveys conducted by Accenture in 2016.

Python’s Continuing Growth

Overall, the Python community continues to grow. Its expansion means we need to talk about what that growth means for our personas in the long run.

Our community is trending younger, which is great for the longevity of the Python programming language. But that also means that we’re getting more community members who associate Monty Python with their grandparents. 

Our community is also trending more global, including programmers whose first language is not English. Only a fraction of Python writing happens in languages other than English and translations are not as common as anyone would like. 

Both of these trends impact how we can write about Python. As more people use Python, we can’t assume everyone will have access to the same media or will get the same jokes. We need to think about the context these readers need, whether it’s an Easter egg explainer or an explanation of why a certain decision was made. 

Humor is tricky when writing about technical topics. Jokes tend to need a lot of context. Even puns require knowledge about pronunciation. Jokes can also age your content faster than technical issues. One additional note about humor: think about who you are making fun of. Punching up is funny. I feel comfortable snarking about Monty Python because the members of that comedy troupe have made serious bank and have legions of fans ready to talk about the good points of their careers. Punching down is boring. If I want to watch someone make jokes at other people’s expenses or use humor to be a bully, I can just watch the news. 

Monty Python’s 50th Anniversary

I’ve mentioned Monty Python in this talk a few times so far and we need to talk about it. When Guido van Rossum named the Python programming language, he was referring to Monty Python, not a snake.

Monty Python is a British sketch troupe who have turned 45 episodes made between 1969 and 1973 into a bunch of movies, books, games, a musical, and a few other things. This year is Monty Python’s 50th anniversary.

I’m making sure to describe exactly what Monty Python is, because we can’t assume that everyone using the Python programming language also is culturally fluent in Monty Python. That’s because Monty Python turns 50 next year. We might as well be asking programmers to get references to The Beverly Hillbillies, Petticoat Junction, or Green Acres. That in itself isn’t necessarily a problem, but some jokes age better than others. Monty Python isn’t aging particularly well. 

By expecting Python programmers to be familiar with Monty Python’s body of work, we’re sending them to look up sketches with titles that include the N word. I don’t think any of us want to accidentally endorse something like that. 

I’m not saying you can’t ever make a Monty Python reference again. I am saying we all have to consider the context of our references before slapping them on projects we want to share with the whole world. I’d ask you to think about it the same way you might think about putting a picture of an actual python in the middle of killing its prey upon your project’s homepage. No matter how cool all of you are with snakes, I am more interested in snake jokes and references than I am in snakes themselves. 

Styles in Python

Within the Python programming community, we’ve established standard styles for code, as well as naming schemas, both formally and informally. 

We have PEP 8, the style guide for Python code, which includes naming conventions for variables, method names, and such. It doesn’t specifically include suggestions for how to write prose, though some of its instructions are just as useful for prose as for code. PEP 8 prioritizes for readability and consistency in code. We can take those instructions to heart when writing.

We also have less formal systems, especially for project names. For instance, many Python conferences and user groups include the city they’re located in their organizational names. Geography is a relatively easy way to disambiguate different local communities from larger overarching communities. We can tell that PyLadies Atlanta and PyLadies Santo Domingo are two separate groups. It gets even easier because there are unique identifiers for different locations in the form of IATA codes. IATA makes sure airport codes are unique, since there are very important differences between Portland, Oregon and Portland, Maine, if only because my home is in Portland, Oregon. IATA’s codes are so convenient that sometimes cities use them as nicknames or identifiers. Not all cities’ IATA codes are exactly intuitive. Chicago airports, you better believe I’m looking at you right now. Those sorts of departures from style — these inconsistencies, if you will — often require explanations so that readers don’t get distracted from a tutorial by trying to figure out where the writer is from.

And while I will always struggle to remember that tickets to both ORD and MDW will get me to Chicago, the sort of “Py*” prefix used in PyLadies has become an easy-to-remember signal that we’re talking about Python. There are a variety ways “Py” has slid into Python project names, beyond just the prefix.

Some projects have chosen words whose letters already include “Py”, like Pyramid. “Pi”, spelled with an I instead of a Y, is pronounced the same way (at least in English), so there are also names that use nonstandard spelling like Project Jupyter. And then there’s the word “Pie”, which sounds like “Py” and is generally delicious. CherryPy, for instance, follows this naming schema.

A lot of projects have developed their own internal naming schema as well and for good reason. When related projects are branded together, users are more likely to realize that they can use all the different pieces you create. BeeWare, for instance, uses a combination of puns — so many puns — bees, and history, to create impressively descriptive names. First off, BeeWare has a subtitle, a full name, if you will. It’s BeeWare: the IDEs of Python. As in, what Julius Caesar was told in Shakespeare’s play of the same name, just before he was assassinated by a bunch of dudes in togas, except they’re referencing interactive development environments, rather than the middle of March.

As it happens, Toga is the name of a BeeWare library which provides wrappers for GUI APIs. Because of course, it is. Just like, of course, the name of BeeWare’s prevalidater is Beefore, with two Es. 

If it sounds like I’m saying a lot of names, that’s because we name a lot of things. We name them pretty fast, too — fast enough that there are multiples sets of projects sharing a name. I’m willing to bet that most of us in this room have heard of Django, the Python-based web framework. But there’s also a piece of tablature software for musicians, also named Django. 

Name collisions are annoying when you’re debugging a program, but they are a full on pain in the rear when you’re trying to search for help online. How many times have you walked away from a meetup or a conference with a Python module in mind to look up once you get home? You really only have three hopes for success for remembering the name: the project has a memorable name, your new contact remembers to forward you that link or you manage to find it through a search engine. You might wind up adding a bunch of keywords to your search terms, adding and removing words until you fight the right incantation to summon whichever library you’re looking for.

And if you’re looking for Python modules to help you with your herpetology research, I don’t even know what to tell you, except that I guess some herpetologists might have made the situation much more complicated by naming a species of python after Monty Python. 

Name collisions are our future, by the way. Unique identifiers are hard and we keeping building new things we have to name.  We need to get used to disambiguating between similarly named tools in our writing as a matter of course.

Disambiguation

Disambiguation is a fancy word which just means clarifying what you mean by a particular word — or name. If, for instance, I’m talking about Python, I’ll say Python, the programming language, not the snake. Just like spelling out abbreviations, you only need to disambiguate terms once in a piece of writing. You can even do it in a footnote if you’re the sort of person who likes footnotes. 

When writing about a programming language with multiple versions, disambiguation becomes even more important. No one enjoys getting halfway through a tutorial before realizing they’re using the wrong version of Python or some dependency. There’s a really, really, really easy solution to this problem, though: NOTE THE VERSION OF PYTHON YOU’RE USING WHENEVER YOU WRITE ABOUT PYTHON. Even if you assume everyone you know is on Python 3, include the version number. Python 4 is mostly a glimmer in people’s eyes, but folks are starting to talk about what might be included when that version comes around. Similarly, there are not only people still using Python 2.7, but even earlier versions. If you only remember one thing from this workshop, please remember to include version numbers. 

While some writers like using links for disambiguation, I’m not the biggest fan. I strongly encourage you to keep your disambiguation, and other necessary context, in your writing, rather than sending readers off with links. There are several reasons.

The first is that I’ve spent a lot of time writing content with marketing in mind. Whether you’re trying to sell a product or win over a new user, you never want to give up a reader’s attention. If you send a reader away, you may not get them back.

The second reason is that not everyone will be able to click links. Most of us are probably used to high-speed internet where we can access everything we need and download every package we see. The only time we really worry about downloading anything in advance is for workshops like this because conference wifi doesn’t always perform well.

But not all of your readers have that experience. I know a Python instructor living in Alaska who relies on satellite internet. When he travels outside of his home town, he downloads packages, updates, books — any large files he needs — because downloading these files at home is next to impossible. In the state of Alaska, around 15 percent of households can’t access internet faster than 10 megabits per second. You can technically watch Netflix with 10 megabits per second, but you’re not going to enjoy it. 

Lastly, even if your readers have high-speed internet, links can break. Even if you’re maintaining and updating the content you write, preventing link rot is tough. 

I’m also not the biggest fan of relying on search to provide context for similar reasons. Expecting readers to google topics doesn’t always end well… I’ve heard of readers winding up on Urban Dictionary pages, learning extremely non-professional definitions.

Clarity

When you’re writing about Python, you have one goal: writing as clearly as possible. While disambiguation is a major pitfall when writing about Python, it’s only one part of clarity. Whether you’re writing support documentation or tutorials, you need some other human to be able to apply those concepts after reading them. That means writing the clearest prose possible (and, if you’re anything like me, some ruthless editing to get rid of any fancy writing that creeps in along the way). Given our diverse audience, there are several tactics for ensuring clarity.

• Choose a tone before you start. As a community, Python is fairly informal. There’s kind of a spectrum to formality, though. While informal tones are great for talks, when you need to relate with other people in the room, they’re less useful in documentation, where a personal tone can distract from key content.
• Keep your sentences short. Especially if you’re sharing instructions, you want a clear and short statement containing one step (or concept). Short instructions are easier to follow, as well as to test.
• Keep your tenses consistent. Check your verbs to make sure they all follow the same patterns — no jumping between the past, present, and future.
• Keep adverbs and adjectives to a minimum. Along with bulking up sentences, too many descriptive words may distract readers from your content.
• Explain antecedents — Keep your pronouns and the nouns they refer to clear. Those nouns that pronouns refer to are called antecedents and you never want them out wandering on their own. 
• Limit passive sentences. They’re often the longest sentences in a given piece of writing, they often rely on unclear pronouns, and they flop around waiting to trip up a reader. If you’re struggling to identify passive voices try adding the words “by zombies” to the sentence. For instance, consider this sentence: “The program was written to automate work flows.” I can add “by zombies” to the end and it still works. “The program was written to automate workflows by zombies” is a clunky sentence but it works. That means the sentence is passive voice and worth changing to something like “I wrote the program to automate workflows.” In comparison, “I wrote the program to automate workflows by zombies” makes no sense.
• Be confident in your writing. Avoid phrases like “I think”, “probably”, or “most likely” as much as possible. This sort of wishy-washy language just gives readers doubts.

Clarity can kinda be measured. You may see suggestions that your documentation and other materials about technical topics should be written with an 8th-grade reading level in mind. Basing your reading levels on some abstract idea of what an 8th grader in the U.S. may be able to read may not provide useful context, but there are various tools (including built-in metrics for some word processors) that smush together data. If your only metric is graded reading levels, you’ll want to write to what your tool considers an 8th grade reading level. These tools are automated, though, and not exactly accurate.

For what it’s worth, this talk is closer to a tenth-grade reading level, because I use words like ‘disambiguation’ and ‘antecedent.’ Technical terms or jargon are usually considered more advanced, without a lot of consideration for whether you explain or contextualize those terms. Consider reading levels a rough guide.

Findability

Findability is just as important as clarity. No matter your use case, people have to be able to find your writing to be able to use it. 

The question of findability overlaps some with disambiguation. We don’t want people researching ancient mystic oracle snakes when they search for Python, after all. And if you want to nerd out with me about the use of oracle snakes in ancient Greek, please see me after.

For some people, findability is roughly equivalent to search engine optimization, or SEO. With SEO techniques, you’re telling search engines how to find your material. Search engines are important, but since our actual readers are humans, we need to go further.

• Use brand names correctly. Python, Django, AWS, and other brand names are recognizable. Making clever jokes or creating your own abbreviations for brand names almost always adds confusion. 
• Include error messages. Whether you’re writing about how to fix one specific problem or discussing how to trouble shoot several issues, include the error messages users may see along the way. People routinely google error messages in order to find solutions, which makes error messages useful for SEO. Error messages also let readers know right away if they’re looking at material that can help them with their specific problem.
• Make your content skimmable. We also want to think about findability within each piece. Humans rarely read a whole document — we tend to want just the information we’re looking for. That used to mean looking at the table of contents and index, but indexes are far less useful for a digital document. When writing for screens, making your content skimmable and searchable is key. If you’re focused on writing clearly, especially in choosing words that will make sense to your audience, you’ll also be writing for findability. To make your writing more skimmable, you’ll want lots of headers and whitespace. If you’ve been coding in Python, you may already be excited about both whitespace and clear labels.
• Differentiate code samples. While Python code tends to be pretty readable, most folks will need a visual cue that they’re reading code, rather than prose. That differentiation doesn’t have to be extreme — just setting code samples in a monospace font, rather than the font the rest of your writing is in, gets the job done.

Once people find your writing, you also need to convince them that you’re trustworthy.

Trustworthiness

Not all writers are trustworthy. I’m not saying that we’re a bunch of scammers, but rather that a lot of writers fail to earn the trust of readers. 

• Respect the reader. Patronizing or talking down to readers is a surefire way to lose those readers. 
• Respect the community. The Python community can feel huge, but it’s really quite tiny when we consider how interconnected it is. None of us know every other single Python user, but I’ll guarantee that most of us are familiar with the same authors, as well as leaders in different areas of the Python ecosystem.
• Be informal (relatively speaking). Companies may need more formal tones, at least in copy, but being able to put a name and a face to a company can be really helpful. I can’t tell you how many software consultancy websites don’t have a single person mentioned by name anywhere on the site. A little personalization can help convince a reader that you know what you’re writing about. If you’re comfortable including a photo of yourself, do that too — you want readers to know that there’s an actual human expert behind your content. 
• Be consistent. Refer to technologies in a consistent fashion — even if it’s not the style other people use. Inconsistencies, even as small as writing PyLadies with a camelcase L versus writing Pyladies with only the first letter capitalized, can distract readers and make them wonder about the quality of the material they’re reading.
• Make time for updating old content. Documentation rot is a thing, and once that sort of rot sets in, readers will be reluctant to continue using affected materials.
• Include images, if you have any. I can send you a ton of studies that humans connect faster with visuals than the written word. But don’t just put a photo of a pair of hands on a keyboard. I invented that. In 2004.
• Write inclusively. I’ve given a whole other workshop about writing inclusively about tech, but the TL;DR is that we have a responsibility to write material that doesn’t make readers feel unwelcome, whether through racist microaggressions, gender assumptions, or even the ability to access material in the first place.
• Avoid obsolete terms. Technology moves fast and outdated material just isn’t trustworthy. This goes beyond technical updates, though. The Python community has mostly rejected terminology like “master / slave.” I don’t want to rehash the whole argument here, but there are two points I want to highlight: whether or not you feel comfortable using terminology like this, there are people who experience pain when they have to use terms that remind them of terrible experiences. Furthermore, slavery still exists today and diluting the meaning of the word “slave” makes it harder to work against the end of such practices. Second, language changes, constantly, and we should expect more changes. 

Consider the word “literally” for a moment. When I tell you that I am literally freezing, you know I’m cold. But am I actually literally experiencing a concerning drop in my core temperature? Not so much. 

Despite my own feelings on the interchangeability of the words “literally” and “figuratively” (and do I ever have some opinions!), the reality is that we haven’t just suddenly agreed to switch the meaning of a word out of nowhere. Different communities use different words in different ways. Language grows and changes to cover new concepts constantly, like how the word “computer” used to refer to a person making calculations, but now refers to a bunch of different types of devices. These changes are routine, through conversation, slang, academic use, memes, translation and literally every other time we communicate. There is a reason English has a reputation for rifling through other languages’ pockets for loose nouns!

Trying to stop the growth of language is like shouting into the wind. Even if it makes you feel better, it’s not effective. And, honestly, most attempts to control language come with a lot of elitist and biased crap. (The history of the word “ain’t” is a basically a primer on classism and language.) Instead, think about how you can stay up to date on how language is being used in the Python community by reading widely within the community and how to update your past writing when changes occur, even if you’re just going with “find and replace”.

The Checklist

I’ve just thrown a ton of information at you. I know from experience that it’s impossible to keep all of these considerations in mind when writing. But, luckily, we live in the future, so we don’t have to memorize this sort of stuff. Instead, we’re going to use a checklist.

When I’m writing and editing, I have checklists that I run through. I write an outline, then I check the list to see if I’m missing something. I write an incredibly bad first draft, then I check the list. I edit that draft into something useful, then I check the list. Why do I check it over and over again? Because I’ve edited out something absolutely necessary more than once and needed to go back and read that material. Checklists help me catch potential issues before they turn into real problems.

• Python version number (and version numbers for dependencies, if appropriate).
• Roughly an 8th-grade reading level (or another metric)
• Up-to-date tech references (and if you ever work on a project for more than a couple of months, don’t be surprised if you need to go through and update these references more than once)
• Get rid of passive zombies and unattended antecedents
• Consistent style, especially when referring to brand names and sharing code samples
• Eliminate huge blocks of text 
• Find visuals, if possible.
• No wishy-washy language. Be confident in your knowledge.

Self-Editing

Some of the errors we caught probably would have been caught by an editor. Many of us don’t have editors, though: unless you’re working in a company with money to market their product, you’re likely responsible for editing your own work or relying on other volunteers in an open source project. 

Self-editing is not enough, no matter how often we have to pretend that self-editing can catch every problem. So what do we do when we don’t have money to pay editors?

Get readers. If you’ve ever written or read fan-fiction — and I’m totally not calling you out either way — you may have heard of the concept of a beta reader. Beta readers go through a draft and tell you where they don’t understand something or struggle with an idea. While most of us aren’t writing Python fan-fiction, the same idea works.

You probably can’t ask one person to read everything you write and give you feedback. Even romantic partners need a break from reading your material. You want to build a list of readers you trust and who are likely to catch things you can’t. Your readers should also be folks who have the privilege of doing this work for free — not everyone can, and asking someone to take on work they can’t afford to do is not okay.

Your list of readers shouldn’t just include technical experts who can proofread Python as well as prose. You’re going to want to recruit readers in several categories.

• Diversity + sensitivity readers. Sensitivity readers grew out of a practice in fiction writing where writers get specific feedback when writing about people or cultures outside of their own experience. But sensitivity readers aren’t just for fiction! They’re really useful for getting feedback on issues you don’t even know exist. For instance, until I worked with an editor of color, I hadn’t really noticed how often we code “black” as “bad”, such as “blacklist” or “black hat.” Those details may seem small, but they can be hugely impactful on how society as a whole sees Black populations. 
• Accessibility + test readers. There are so many mechanics that go along with publishing information that can prevent readers from using that information. We’ve already talked a little about how slow internet connections can make our writing inaccessible, but there are many different layers of accessibility. I just finished a project where I needed to ensure that readers with visual disabilities could fully access all materials. In print, that meant using larger type and specialized typefaces. In digital formats, that means making sure your material can be accessed by screen readers and other tools. Asking readers to test your work on multiple devices and platforms is one of the only ways to check your accessibility; while there are standards, a surprising number of websites and publishing tools don’t meet them.
• Usability + technical readers. Having someone with equal or greater Python experience review your work for technical accuracy is always a good idea. But consider bringing in a reader who is less experienced as well. I’ve even brought in nonprogrammers to read programming materials because they can spot some errors more effectively because they don’t have any implicit knowledge about the topic. A person with a little distance from the project can also help you catch jokes that are hilarious to you but rely on insider knowledge. Sometimes those sorts of in-jokes confuse or exclude people, making it even harder to get up to speed with a new library.  Feel free to ask your family to read over your writing, provided that they’re good at giving feedback. You can never guess who will run into what information and interact with it online. You certainly can’t control who learns about given technical topics — if you could, every member of my family would be banned from ever seeing the word “Bitcoin”. Your family members count as one person in this case, by the way. You can probably assume that your family’s background is close enough to your own that you’ll want to make sure to get some other opinions. Stakeholders. Even when we’re writing outside of commercial settings, we typically know other stakeholders in a project. Depending on what kind of project you’re working on, your stakeholders could include employers and their lawyers, project contributors, and all of your friends who listen to you talk about this project incessantly. That last group should be allowed to opt out.
• Editors. Lastly, if you can, find the money to pay a professional editor, especially on big projects. It may cost less than you think — and it almost certainly costs less than making a mistake. A lot of editors aren’t in a financial position to contribute to open source for free, so money remains the best way to get them involved.

Persuading folks to work on unpaid projects is never easy. I’ve had some luck creating a sort of editing round robin for certain types of projects — like a group who all look over each other’s resumes and give feedback. 

Whether you’re self-editing or working with other people, give yourself time between passes on your work. Even a day or two can make an article feel fresh. Read suggestions and edits before implementing them, as well. Taking criticism can be tough and giving yourself time to feel your feelings before trying to fix your writing will result in better changes.

Editing Tools

The best editing tools are those that have been in use for a while. Most of the bugs have been worked out of style guides, for instance. Style guides started at newspapers, covering details like how big headlines should be and how to correctly refer to government officials. Designers acquired the idea, creating design style guides with details like exactly what colors are in a company logo and and reusable style elements. Then developers got with the idea and created development style guides, like Python’s very own PEP8. PEP8 covers details like file naming and versioning conventions, along with style suggestions like including whitespace.

In terms of style guides for writers, we have plenty of options. My first love was the AP Stylebook, which is used by a lot of newspapers and other print media. Maybe I’m easily thrilled, but I adore style guides. They’re basically reference guides of just the information you need to work on a particular type of project. I actually make my own style guides just for funsies: not only am I the editor of The Responsible Communication Style Guide, but I also make style guides for basically every project I work on, whether it’s for a blog, a book, or documentation. I write down all the project-specific information, like how each participant’s name is spelled, along with the latest technical jargon, and all the other resources I know someone else will use. 

You may have more than one style guide on your desk when working on a project. In fact, you *should* have more than one style guide. It’s a question of graceful deprecation — you need a project-specific style guide, but having an industry-specific style guide and a more general guide like The AP Stylebook or The Chicago Manual of Style. 

It’s easy to build up a whole bookshelf of style guides. There are references like The Chicago Manual of Style, industry-specific style guides like The Bluebook which covers legal documents, organization-specific style guides like The Microsoft Manual of Style for Technical Publications. Depending on the project you may need more than one style guide — you might use an internal style guide when you’re writing documentation, then need to grab something broader to look up what your internal guide doesn’t cover. Sometimes you may need to even pull a more general guide off your shelf, like the Chicago Manual of Style. It’s a somewhat graceful deprecation, keeping the guidelines we need close at hand, with a fallback plan for anything an internal guide doesn’t cover.

Style guides are routinely updated, by the way. The AP Stylebook will definitely have more updates in the future, from new technology terms to updated discussions of sports statistics. In fact, that’s their entire business model: journalists are encouraged to buy a new copy every single year. Most of us only update our copies every couple of years, but we’re used to thinking about at least this one specific tool as something that needs to grow and change with the language it describes. 

That assumption of change is really useful when we talk about how to improve the systems and tools we rely on. It provides a framework where we can find ways to do better, ways to update our expectations as we learn, ways to improve on our communications. Sometimes it takes more time than we like to make these changes. (It took the Associated Press until 2016 to agree with the rest of us that “internet” shouldn’t be capitalized.) As it happens, though, there’s nothing to stop you from opening up a text doc and writing your own style guide. I’ve been doing that for years, which led me pretty much directly to giving this talk.

There are plenty of startups out there who are excited to offer you some sort of cutting-edge automated editing tool. Grammarly and Hemingway are both pretty well-known. These tools are to spell-check as what integrated development environments are to Notepad.

That power doesn’t necessarily equal out to good advice, though. Hemingway, for instance, relies on rules created by Ernest Hemingway. Leaving all his other issues aside, Hemingway was a decent writer — but not everyone writes like Hemingway and Hemingway’s style doesn’t fit all use cases. For instance, Hemingway was opposed to all adverbs and most adjectives. But sometimes we need both adjectives and adverbs to fully explain a process, especially if we need to explain technical jargon. If Hemingway’s rules don’t work for you, that’s okay.

If you’re writing in a language other than English, there may be more effective automated tools. English, however, rummages for spare nouns between seat cushions. It’s a difficult language to analyze for the same reasons that it’s hard to learn: English is secretly a stack of three other languages in a trenchcoat just looking for norms to break.

Some of these tools also have dangerous flaws. Tools like Grammarly work by tracking what you’re typing. That means they’re keyloggers. By default, Grammarly’s browser plugin sees everything. Including passwords. Personally, I really like Grammarly and still use it, but I do so without keeping the browser plugin constantly active. In the short-term, though, expect automated editing tools to continue having quirks and issues.

Writing Tools

While a lot of tooling focuses on the editing side of things, there are a few writing tools that are effective. Templates are hugely helpful.

Just to disambiguate, I’m talking about about written templates: documents with blanks we can fill in like Mad Libs. I’m making a point to specify because I am not talking about templating engines.

There are some tools, like TextExpander, which can be used to fill in pre-existing templates on the go, but a lot of writing templates are just text documents with sections where you can put materials. I create a lot of templates for my work, because I do a lot of work that needs to be consistent. I also really hate staring at blank pages at the beginning of a project. If I have a basic template to fill in, I already have a starting point. For blog posts, for instance, I know I always want to end with a call to action — something that the reader can immediately do, which may or may not benefit me, depending on what I’m writing.

Calls to action are easy to template. My template is just three words: “Do the thing.” I know that I have to give readers a concrete action to follow, with a clear action verb. I’ll add context and detail as appropriate, but I always start writing my calls to action by modifying “do the thing.”

I generally don’t set out to make templates, by the way. Before I write a new project, I rummage through past projects for similar pieces that I can use as a template. Then I make a copy and delete all the bits I don’t need. If I find a particular template useful, I’ll clean it up and save it with the rest of my templates.

There are plenty of writing tools out there. Word processors are, of course, standard. A lot of writing tools are like time management apps, though: people tend to create tools that work perfectly for their specific use case. For someone following similar workflows, such tools can be useful — but if you have a different workflow, such tools can be tough. 

Scrivener, for instance, is a big fan favorite for writing long documents. It’s got a slew of features for keeping track of references, reorganizing chapters, and so on. I can’t use it. My workflow just doesn’t match up, because I look for feedback at multiple steps of my writing process. I’m also all about the brain dump, rather than a strictly outlined approach. In fiction communities, by the way, this debate is often referred to as ‘outlining versus seat-of-your-pantsing,’ meaning that you just start writing and see where you wind up. I do think of myself as more of a pantser.

Writing workflows are intensely personal, so don’t be surprised if the new hotness doesn’t make your writing process any easier. Try out tools, of course, but you’ll probably get more writing done if you’re writing, rather than trying out tools. 

Lightning Talk Submissions

We’re going to try out a template now. This template is for lightning talk proposals. I’ve ran lightning talks submissions at a couple of conferences, as well as given plenty of lightning talks myself. I got over wanting to craft that perfect individual proposal around the time I gave my second lightning talk.

This template covers most of the information you can be asked for when prepping a lightning talk. It’s not entirely universal, but it’s enough to fill out just about every lightning talk submission form I’ve seen. 

Talk proposals have to be persuasive: anyone submitting wants to speak and you need to make sure your proposal stands out. I know that templates can seem like a weird tool in situations where conformity isn’t useful, but once you get into using this particular template, I think you’ll find that a template lets you focus on writing persuasively, rather than trying to make sure you dot every i and cross every t.

So who is the audience for a talk proposal? It’s not the folks who will hopefully be listening to you speak. Rather, it’s the person who approves or rejects talks. Keep that in mind for filling out this template. It’s kind of a secret, but certain details in your proposal aren’t exactly carved in stone if you get accepted.

Let’s go over this really quickly and then we’ll take a few minutes to each write our own proposal.

• Name + email address. In your own template, you can just add this information and not update it.
• Short bio. By short, I mean maybe two lines. These two lines need to demonstrate that you’re a great person to give this lightning talk. For instance, if you want to give a lightning talk about Python, your bio might mention what you do with Python.
• Talk title. I know it’s tempting to be super clever here. I want you to resist the urge, because sometimes the folks deciding on lightning talks skim titles and then decide which proposals to read more deeply. You want something really straightforward and clear, so that your talk gets thr0ugh the initial review process. This, by the way, is one of those details not carved in stone. I routinely will fancy up the title of a a talk when I’m making slides, especially if I can think of something that will appeal to my audience. 
• Talk description. This is where the magic happens. Because lightning talks are short, this section doesn’t need to be long — but it does need to be interesting. If you have some big reveal in your talk, include it in the proposal. Don’t leave reviewers guessing about whether or not you’ve got something interesting to say. And I promise reviewers almost never give away a good twist ending.
• The big idea / takeaway: What, exactly, do you want your audience to learn during your talk?

By the way, just following directions and filling out submission forms completely will put you ahead of a surprising number of other potential speakers. 

I’m going to give you a few minutes to fill this out.  If you have an idea for a lightning talk, awesome!

If you don’t have any lightning talk ideas on tap, don’t stress — you can propose a talk about why a new programmer should choose Python over another programming language. We’re talking about the writing here, not the content of that writing. 

Python’s Valuation of Writing

Python and Django both boast amazing documentation free to anyone with an internet connection (and some without). Creating that documentation was perhaps easier because of the availability of a cohort of programmers and documentation writers trained in communication.

We can’t assume, however, that all Python projects will start at newspapers or other media companies. In order to maintain the high documentation standards in this community, technical writers, programmers, and other Python contributors need communication resources. In order to build and maintain these resources, we need to talk about money.

Writing about Python is work; on the same level as coding the software, designing the interface, or testing its security. In an ideal world, every software development team would include at least one technical writer. While this isn’t an ideal world, the costs of documentation, particularly in Python, may not be insurmountable. 

The Python community’s commitment to open source obviously impacts the finances of anyone choosing to work on Python projects, as well as how Python projects (as well as organizations using Python) can generate revenue. Most projects need at least enough revenue (through donations, sales, or whatever) to cover maintenance costs, relying on contributors to subsidize labor costs by providing their own time for free. But providing labor for free (at least under capitalism) can limit both a project’s growth and contributors’ abilities to meet their own needs.

The result is a set of financial patterns seen throughout the Python community:

• Offering limited documentation for free, while charging for access to full documentation
• Offering paid training
• Offering paid support beyond documentation
• Writing educational materials for larger publishers
• Hosting installations of free software

These approaches to raising revenues have met with variable success in the Python world. In particular, charging for access to full documentation is controversial. Open source advocates consider free and accessible documentation a core tenet of any open source project. As Jacob Kaplan-Moss put it, “There’s a particularly pernicious anti-pattern in documentation where tutorials are provided for free but the real documentation is only available for purchase. At best that’s lazy and sloppy; at worst it’s downright evil. Free software needs free documentation. If you’ve got otherwise you should be ashamed of yourself.”

Evil may be a strong word but the reality is that there are plenty of organizations that have figured out how to fund open source work without charging for documentation. For instance, Django’s documentation is available for free, while many community members rely on paid training to pay the bills.

But that’s not necessarily enough to meet the needs of Python’s growing community. No matter what position you find yourself in, I encourage you to advocate paying writers and editors. Whether you can get money out of the marketing budget to pay bloggers, out of technical budgets to pay documentation writers, or out of diversity and inclusion budgets to pay sensitivity editors, every little bit will help us continue to create amazing free materials for the Python community. 

Furthermore, be a good citizen of the Python community, especially when it comes to writing and editing. Support other writers and make sure they get credit for their work. Be empathetic when you see typos — and send a pull request to fix those typos when you can. Don’t ever be a jerk to someone writing documentation for free. Being a jerk about a typo may mean the difference between a documentation contributor staying in the community and leaving.

Writing for Other People

So far we’ve mostly focused on writing and editing on our own. But one of the joys of belonging to a thriving open source community is that we can work with *other people*. Sometimes, we can even get paid writing work! 

But we do need to know how to play nicely with others to access those opportunities. So what opportunities are there to write about Python?

• Talks: Writing talks to deliver at PyCon and other conferences
• Documentation: Document software you or other folks have created. Documentation, by the way, is often suggested as a great entry point for new contributors who aren’t confident in their technical skills. That’s a little like having an intern handle social media, in my opinion, but that is an entirely different soap box. While documenting open source projects is usually a labor of love, many companies will happily pay documentation writers, both as employees and on a contract basis.
• Blogs: You may have your own blog or website, but there are loads of different websites running material about Python. The PSF blog, for instance, welcomes guest posts and hires freelance bloggers. There are also loads of websites looking for both written and video tutorials, which tend to get premium rates when compared to articles.
• Books: I am not necessarily recommending you write a book, especially if you’re doing it for the money. I’ve written several books and I don’t think I’ve earned enough to cover my time in sales from any of them. That said, if you have a book inside you bursting to get out, there are loads of publishers with Python lines. Maybe see me after if you’re considering putting in a book proposal soon — there are definitely some publishers I would recommend working with over others.

When you’re writing different materials about the same topic, it’s worth noting that you can repurpose material. If all your writing is focused on Python, you may be able to create new work with less of an upfront investment.

For instance, if I was pitching a Python book right now, I’d write somewhere between ten and twenty really in-depth blog posts, and then edit them into more of a book format. You usually can’t use the same material word for word — that’s considered self-plagiarization in a lot of circles — but you can use the same information and the same format to make something new. 

Aside from getting two projects for maybe 1.5 times the work, this approach gives you material to persuade editors and publishers, along with conference content committees, to take you more seriously. If you’ve got published blog posts about a topic, you’re an expert in that topic. You may not be the most knowledgeable expert in the world on that topic, but the research necessary to write a bunch of blog posts is far more research than most people have done. It makes you a known quantity, with proof that you can write about that topic. Most editors and publishers will want to see samples of your writing before committing to a project anyhow, so you might as well make those writing samples do as much work as possible.

A lot of sites that routinely publish freelance or guest writing will have other requirements as well. Luckily, they’ll often share these details so that we can easily review them and submit our writing. These submission guidelines can vary from a few sentences and an email address to a fairly elaborate document laying out not only writing requirements but publication-specific styles. 

OpenSource.com Submission Guidelines

Let’s take a look at the submission guidelines for OpenSource.com. Their guidelines are pretty detailed, which makes them relatively easy to write for. 

• They tell us the technical details of how they want writers to submit work — where to send articles, which file formats to use, and so on. In general, you don’t ever want to deviate from these instructions.
• They give us a site-specific style guide so that we can make sure we get tone and formatting correct.
• They tell us what kind of articles they’re looking for, including how long those articles should be.
• They tell us some information about our audience, explicitly pointing out that some of the site’s readers are newer to technology. I’d probably use Pat’s persona to figure out how to write this article, because Pat generally matches up with this description. I do think we can assume that Pat has a little bit of Linux experience, even if they aren’t primarily Linux users.
• They tell us how the material will be licensed. If you’re concerned about reusing material or getting paid for it, pay attention to what rights you’re assigning to a publisher. In this context, a Creative Commons license makes sense. 
• They also tell us about their backlink policy. Because a lot of folks use guest posting as a way to manage their ranking in search engines, a lot of publishers have become very careful about how they handle links. You’ll see this sort of policy much more often on sites that don’t pay writers, because most people don’t write without getting at least a little something out of it.

I do have to point out that a lot of websites would much rather hear your idea for an article and then help you develop a draft, rather than receive a mostly complete article. Personally, I prefer not submit full articles to sites I’m not already familiar with — OpenSource.com is a known quantity and I trust their editors not to be jerks, but there are editors and publishers out there who will take advantage writers who are willing to write without a confirmed acceptance. 

One of the reasons that we’re looking at OpenSource.com is that one of their editors is attending PyCon and is actively looking for folks to write for the site about Python. OpenSource.com doesn’t pay contributors, but if you can afford to write without pay, it can be a beneficial place to get a byline.

The other reason is because we’re going to write short articles right now, using all the stuff we’ve been talking about.

Let’s Write Something

Exercises that reflect what you’ll experience are always better than something that can only mimic reality. Our last exercise today is going to be writing an article that meets these guidelines from OpenSource.com. I am going to add a couple of additional constraints to make sure we can both practice the skills we’ve covered as well as make enough progress in the time we have left for me to give you personalized feedback.

For this exercise, you’re going to describe a Python library and explain its value. Try to pick a library you’re familiar with because we don’t have a lot of time to devote to research. This sort of article meets the requirements for OpenSource.com’s for 500 to 600-word articles. However, I don’t expect you to write a full 500 words before we wind down this tutorial.

Even if you identify as a pantser and you like to just dive into writing, I’m going to ask you to outline what you’re going to write. They don’t have to be complicated, but they’ll help us discuss what your article might entail if you hit 500 words. Your outline should answer three questions:

• What’s an example of how this library has been used? We’re talking real world examples here. 
• What do I need to know to be able to use this library?
• How is this library better than competing libraries?If you truly can’t find any competition even by googling, you can tell me that instead.

Pat the Newer Dev needs you to answer these questions before they can decide whether learning about this library is worth their effort.

Don’t worry too much about getting spelling and grammar absolutely correct. This is your first draft and I’d normally suggest doing at least a quick editing pass before handing it over to someone else, but we only have so much time. I promise that all of my first drafts are terrible and that I won’t judge you.

Conclusion

Remember how I was talking about reusing and repurposing your material? As it happens, 500 words is about the right length for a 4 or 5 minute lightning talk. Y’all have just written lightning talks (though you might need to tweak language in order to give it as a lightning talk) discussing a specific library. Nice, right?

As we wrap up, I have just a few last things to say. First, writing is one of those skills that you can only build with use. The best way to improve your writing is to write as much as possible. The second best way is to read as much as possible, preferably from a wide variety of sources. The more time you spend with language, the better equipped you’ll be. 

Also, in case I haven’t said this enough times, ALWAYS ALWAYS ALWAYS include version numbers. 

Lastly, I want to point out a couple of great resources on writing:

• Jacob Kaplan-Moss wrote a blog post series about writing about Python in 2009. The series may be ten years old, but it’s still a good resource. (https://jacobian.org/2009/nov/10/what-to-write/)
• The Responsible Communication Style Guide and the Python Style Supplement
• Sin and Syntax by Constance Hale is a book I strongly recommend if you want to learn more about writing prose outside of the context of the Python community
• Write the Docs has videos online of years worth of talks about writing and they tend to be really good. As you’re looking for ways to level up after this workshop, watching these videos can be really helpful.