As a professional writer, I frequently get asked, “as a ______, how can I get better at writing?” I’ve never had a good list of resources to point people to, so I finally decided to write one. I’ve worked hard to become a good writer, and I’ve had the privilege of many good teachers along the way.
If you’re not really sure why your writing isn’t as good as you want it to be, that’s okay. In this blog post, I’ve identified the strategies that I use to write well. I hope they’re useful to you.
Where to start
Read and write more frequently. You can’t get better without good examples or practice. If you want to get better at writing you need to read more and you need to write more.
Identify what you’re trying to improve. Maybe you struggle with grammar, or in clearly communicating your ideas. Maybe it takes too many words for you to get your point across, or you can’t quite connect with the people reading your writing.
Write accurate content by improving your grammar and word choice
Use a tool like Grammarly, or enable grammar checking in whatever tool you use to write, if it’s available. If you don’t want a mysterious AI reading your writing, you can use other resources to improve specific aspects of your grammar.
Some key concepts to focus on:
- Understand verb and noun preposition pairs. See Kenneth Beare’s guide Verb + Preposition Combinations on ThoughtCo., or this Preposition Combinations with Adjectives, Nouns, and Verbs PDF from Washtenaw Community College, including a worksheet for practice.
- Understanding complementary verb and noun forms, to help avoid nominalizations. When you use the noun form of a word, you can easily obscure your meaning. See How to Improve Your Writing: Avoid Nominalizations on Wordvice.
- Review easily-confused words, often homonyms, to identify words that you might be consistently misusing. This Homonyms Main List from an English learning Russian website is fairly exhaustive.
- Look words up in the dictionary. If you’re not sure you’ve used a word correctly, or used the correct spelling of a word, look it up. I do this almost every day. I’m partial to the Merriam-Webster dictionary.
I still struggle with the following (more pedantic) grammar rules:
- When do I need to use a hyphen to connect two words? See Hyphen Use, on the Purdue Online Writing Lab website.
- Did I split an infinitive? What is a split infinitive, anyway? See Infinitives, on the Purdue Online Writing Lab website.
- Does my relative pronoun actually clearly refer to something or do I have a vague “that” or “it”? See Pronouns in the Splunk Style Guide.
The somewhat silly yet practical book, Curious Case of the Misplaced Modifier by Bonnie Trenga, might also be a useful read.
Write helpful content by defining outcomes before you start
Before you start writing something, whether it’s a slide deck, an engineering-requirements document, an email, or a blog post like this one, consider what you want someone to do after reading what you wrote.
Often called learning objectives or learning outcomes in instructional design, defining outcomes can help you write something useful and focused. Sometimes when you’re writing something, other extraneous ideas come to mind. They can be valuable ideas, but if they distract from your defined outcomes, you might want to remove them from your main content.
Some example outcomes are:
- After reading this blog post, you can confidently draft a clear document with defined outcomes.
- After reading this engineering requirements document, my colleague can provide accurate and helpful architecture feedback on the design.
- After reading the release notes, I can convince my boss that the new features are worth an immediate upgrade.
I also want to note that if you write an outcome focused on someone understanding something, rewrite it. It’s tough to measure understanding. It’s easier to measure action. For that reason, I try to write outcomes with action-oriented verbs. For more about writing good learning objectives, see the Learning Objectives chapter in The Product is Docs.
Write focused content by identifying your audience
Who will be reading your writing? What do they know? Who are they? What assumptions can you make about them?
If you can’t answer these questions about the people reading your writing, you won’t be able to clearly communicate your ideas to them. You don’t have to be able to answer these questions with 100% certainty, but make the attempt.
If you recognize that you’re writing something for multiple audiences, consider breaking up the content into specific sections for each audience. For example, architects might care about different content than a UI engineer, a product manager might care about different details than the backend engineer.
If you identify the different needs of your varying audiences, you can write more consistently for each specific audience, rather than trying to address all of them all the time. For more on identifying your audience, see the Audience chapter of The Product is Docs.
Write findable content by considering how people get to it
How people get to your content can influence how you write it. If people use search, an intranet, or direct links to find your content, you might make different decisions about how to structure it.
I always assume that people are finding my content by searching the web. They’ve typed a specific search query, found my content as a result, and open it with the hopes that it is the right content for them.
Consider what people are searching for that can be answered by your content, and write a title accordingly. Spend time on the first few sentences of your content to make sure that they further clarify what your content addresses.
For example, I titled this blog post “How can I get better at writing?” because I expect that’s what a lot of people might type into their preferred search engine out of desperation. I could call it “7 quick tips to improve your writing”, but that’s not how most people type search queries (in my opinion).
Mark Baker’s book, Every Page is Page One, covers a lot of information related to this concept. He coins the term “information scent” to describe the signals that indicate to a person that they’ve found the right content to answer their question, and “information foraging” to describe the process of looking for the right information.
Write readable content by considering the structure
People aren’t excited to read technical content or technical documentation. No one rejoices when they get an email. I get paid to write technical documentation and I still avoid reading it if I can. Because people don’t want to read your content, structure it intentionally.
Write for skimming. Bullet points are often better than paragraphs. Tables are often better than paragraphs.
Put information where it needs to be. If you’re writing a series of steps, make sure the steps are actually in the right order. For example, if something needs to be done before all the steps can succeed, put it before the set of steps as a prerequisite.
You also want to consider the desired outcomes of your content and your audience when you structure your content. It can make sense to focus on one audience in one piece of content, or one desired outcome in one piece of content. Don’t try to do too much in one piece of writing.
Nielsen Norman Group has an incredible set of research and recommendations about how people read and how you can structure your content. I recommend the following articles:
- F-Shaped Pattern of Reading on the Web: Misunderstood, But Still Relevant (Even on Mobile)
- Inverted Pyramid: Writing for Comprehension
- How Chunking Helps Content Processing
Write clear content by intentionally choosing your words
You want to make your content easy to find and easy to understand. To do this, you need to be consistent and intentional about the words that you use.
Use consistent terminology. This isn’t the time to write beautiful prose that uses different words to mean the same thing. Don’t overload terms by using the same term for multiple things, and don’t use multiple terms to refer to one thing. Use the same terms and use them consistently.
If something is a JSON object, call it that. Don’t call it a JSON object sometimes, a JSON setting other times, or a JSON blob other times. Pick one term and use it consistently. You might have to pick an imperfect term and live with it. It happens! There are only so many words to choose from.
Be intentional about the words you use. Consider the words that your readers use to describe what you’re writing about, and use the same words if you can. Even if those words don’t match up completely with the feature names in use by your product.
If all of your software’s users refer to “dark mode” instead of “dark theme”, you might need to use both terms in your content so that people can find it. For some internal documentation, you might need to make a mapping of internal names that people use for something with the external names used in the product.
If you’re not sure what term to use, find out what terms your readers are already using. If you have access to search query logs of your website search, review those for patterns. If you don’t already have readers or users for your product, you can do some competitive analysis to understand what terms are in common usage in the market.
Nielsen Norman Group again has some excellent resources on clear writing:
Write trustworthy content by thinking about the future
Errors in content, especially technical documentation, lead to mistrust. When you write a piece of content, consider the future of the content.
The future of the content depends on the purpose and type of content that you’re writing. This list contains some common expectations that readers might have about various content types:
- A blog post has a date stamp and isn’t kept continually updated.
- Technical documentation always matches the product version that it references.
- Architecture documents reflect the current state of the microservice architecture.
- An email gets the point across and can’t be edited after you send it.
You must consider the future and maintenance of any content that you write if your readers expect it to be kept up-to-date. To figure out how difficult maintaining your content will be, you can ask yourself these questions:
- How frequently does the thing I’m writing about change?
- How reliable does my content need to be?
- How quickly does my content need to be accurate (e.g., after a product release)?
By answering these questions, you can then make decisions about how you write your content.
- What level of detail will you include in your content?
- Will you focus your efforts on accuracy, speed, or content coverage?
- Do you want to include high-fidelity screenshots, gifs, or complex diagrams?
- Do you want to automate any part of your content creation?
- Who will review your content? How quickly and thoroughly will they review it?
For more on maintaining content and making decisions about your documentation, see the Documentation Decisions chapter in the book The Product is Docs (which I contributed to).
Feel empowered to write better content
I hope that after reading this blog post you feel empowered to write more accurate, helpful, focused, findable, readable, clear, trustworthy content. This is an overview of strategies. If you want to dig deeper into a specific way to improve your writing, check out the books and articles linked throughout this post.
If you have something you think I missed, you can find me on Twitter @smorewithface.