How can I get better at writing?

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:

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:

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. 

You can also check the dictionary or use a tool like Google Books Ngram Viewer or Google Trends to identify common terms for what you’re attempting to describe. 

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

My impressions from the 2017 Bay Area Book Festival

For the second year in a row I attended the Bay Area Book Festival. A collection of authors, publishers, readers, and other bookish sorts also show up for the weekend in Berkeley. This year, like last year, I discovered some great sessions that led me to think about things from a new perspective and that I might not otherwise have learned about.

One great thing about the book festival is that, true to its slogan, it connects readers and writers. Much like the podcast Song Exploder, the sessions caused me to think far more about the process behind creating the things I love than I might have otherwise.

Something that struck me and my friend, however, is how few of the attendees were young. There are a lot of attendees (of sessions, especially) that seem to be retired, quite a few middle-aged people, and in the YA-fiction sessions I attended, a good number of children and their parents. In fact, much of the festival seemed designed to be family friendly.

However, in a reflection of publishing at large (perhaps) the festival neglects the population that is most clearly present in Berkeley and the Bay Area to me—the ~ * millennials *~ that attend the university and work in tech and other industries all around the bay. I saw a few other people in their mid-twenties and mid-thirties, but not nearly as many as I’d hope to see. No one that I talked to in that age range (save my friend) knew about the festival that weekend, and I saw almost no marketing for it aside from the emails from the organizers (thanks to signing up for the email list last year) in the social media sites and feeds that I follow. Hopefully in future years this will change.

I also struggled to determine who the actual target audience of the festival was based on the sessions I attended and the booths I witnessed wandering around (I’m not much of an actual booth-visitor). The fest again, advertises itself as connecting readers with writers, but it seemed to be connecting writers with other writers just as often. Whether on panel discussions or through writer-oriented booths in the park, that was a very present and understandable theme. I’m not sure it matters that the target of the festival is so broad, and perhaps it might flourish even more if it were more explicitly targeted to this wider audience. But again, perhaps not.

I attended two sessions each day of the festival, and here are my impressions of each of them.

Saturday

The first session I attended on Saturday was called Worlds We Create: Young Adult Fantasy Writers on Creating Alternate Realities and Memorable Characters. It’s only in the last year or so that I started realizing that I do read fantasy and sci-fi novels, and while I didn’t seek them out when I was younger (sorry, Tamora Pierce and Phillip Pullman), I always enjoyed historical fiction and fairy tale retellings. This session was explicitly about how fantasy writers go about creating the worlds in their novels. The moderator had some great questions, they asked about how authors develop characters to reflect the world they inhabit, whether the story or the characters or the world come first, and more.

They discussed using “sensitivity readers,” a concept I hadn’t heard of before this panel, who you can hire to provide feedback and criticism about the way that you’ve told the story of a character with experiences that you haven’t had directly. One of the authors, who set her latest book in turn of the century New York City, spoke of the balance of being sensitive to certain life experiences and having to confront discrimination with the focus of blowing it up in the book.

Needless to say, I’ll be thinking a lot more about the quality of worldbuilding after this panel. I was in the midst of reading a series that was set in a world that took awhile for me to understand, and seemed to use a glossary to attempt to offload some of the worldbuilding heavy lifting, yet the story and the characters were fairly well-developed enough for me to appreciate it and continue following through. The balance of world-building time and story-telling time was also covered in the panel, with one of the authors mentioning that she’ll use worldbuilding as a way to get started writing a new book if she’s struggling with how to start.

The second session I attended on Saturday was rather different from the YA fiction panel. This session featured Masha Gessen in conversation with Orville Schell on Truth, Lies and Totalitarianism in Russia and the U.S.. This session featured quite a few great moments. My friend pointed out that she hadn’t before heard someone speak with such attention to the precision of their language, yet that is exactly how Gessen spoke. She was very precise when agreeing or disagreeing with Schell, and didn’t mince words.

Some paraphrases of what she said in the session, along with my own characterizations about what she said, follow.

Totalitarianism succeeds through destruction… not durability of the presence of totalitarianism or genetic makeup or expectations but of the absence of shared understanding and society and other things that help you move forward in the face of it.

She took care to distinguish her perspective from that of Schell’s. He asked a question about whether totalitarianism or autocracy persisted in some countries due to the genetic makeup of people or due to a durability of the people, and she disagreed, though recognized that they agreed on the state but not the cause of the state. The absence of certain things, rather than the presence of something, is what is helping totalitarianism succeed and persist in these nations.

We’ve constructed a story about what happened in post-soviet states but not what happened in the west… democracy isn’t a state achieved by a country but a spectrum (becoming more or less democratic)

I really appreciated that she mentioned this. As someone who studied post-soviet states in college, I am quite familiar with the stories constructed there, but I hadn’t considered this perspective until she mentioned it. In my recent travels and events in the United States, it’s become clear that the Western states didn’t pay much attention to developing an identity that didn’t position other states as enemies and actively maintaining democracy.

Gessen also mentioned, perhaps in response to an audience question, why Trump admired Putin so much. In response to that, she referenced Tim Snyder in the NYRB, who wrote “Putin is the person that Trump plays on TV.” Expanding on that point, she continued that “Trump talks of power, off the charts popularity, and control… but doesn’t really understand where that comes from.” And where that comes from is autocracy. They also discussed her own article in the NYRB about autocracy.

Also discussed was the differing perspectives of politicians, businessmen, and others in an autocratic state compared with a democratic state.

There’s this belief from Russian politicians, journalists, businessmen that everything can be bought or is for sale or is transactional… a few years ago that didn’t fly here but that’s changing here… apparent struggle to understand non-transactional motives in authoritarian societies and possible explanation for a lack of understanding of civil society… If public service and nonprofit motives are questioned or not understood then democracy is challenged

Schell also brought up countries that don’t deal with history in an honest way (like many totalitarian states, Russia or China especially have quite censored and limited views of their own past), she spoke of WWII as being a touchstone in Soviet history in rewriting the past, but also continued to discuss whether a society can move forward with a distorted view of the past.

All societies have distorted views of the past…that’s trauma that societies have to deal with. Estonia for example has done a good job with this: “we trust one another, we were under occupation, and we’re going to rebuild based on that trust.”

Germany had the advantage of short period of time and everyone could remember pre-totalitarianism and talk about perpetrators, bystanders, and victims…. but it’s totally muddled in the Soviet Union; people were both perpetrators and victims and no one was a bystander.

How do you take responsibility for your own past if you messed it up? Whitewash the history…

One of the things that she mentioned as being most challenging for rebuilding in (or after) a totalitarian or autocratic state was imagination.

How do you rebuild when you can’t imagine a future or a past…and sometimes you can’t imagine the present because it’s so awful that you can’t fathom it…you reach for the past and confuse lack of imagination with understanding

When asked about her hopes for Russia in the future, she was blunt. “Russia is hopeless, scorched earth.” She did expand in response to a follow-up question to discuss the small-scale successes of some friends of hers in starting focused community organizations, but acknowledged that people seeking to make change on a small scale, while inspiring, is a way of admitting defeat. After you start focusing almost exclusively on small-scale change, you’re no longer trying or dreaming of making those changes on a large scale.

Sunday

Sunday I slept in, so I skipped an earlier morning session I considered attending so again attended two sessions.

First I attended another YA fiction session, Reality Bites: Fiction About Teens’ Real Lives, which was really great. Another panel discussion, the authors discussed what they do when they write most of a book and realize it isn’t working, sometimes all you can do is “upcycle” some of the scenes into other books. The moderator also asked about recurring themes and iconography, and while one author mentioned trees (she writes largely thrillers that tend to involve the woods), another author mentioned that she often writes about the sky, likely because it represents us against the vastness.

Most relevant of all, I thought, was the discussion on how writing novels teaches you to be compassionate about multiple points of view. Kim Culbertson especially made some great points about this. Sometimes a character has to do something differently than the way you would. She mentioned that “Lots of people are uncomfortable when they hold themselves up to another person and the edges don’t match.” But she likes to challenge that in a way, to help people get to the understanding and consideration that other people are different from you and that may seem strange but it’s actually awesome, and we need to recognize that!

 

 

The second panel I attended was about immigration and identity, Living in Two Worlds: Crossing Borders and Identities to Create Home. The moderator asked each author in turn to speak about their book which led to a great focused discussion on the themes in each one.

First, Laleh Khadivi discussed her book and the challenge about writing about two worlds, especially that “one world is never going to believe the other world.”

Next, Lesley Nneka Arimah discussed her book of short stories. She mentioned that she included Facebook in one of her stories because she was tired of reading stories set in contemporary Africa that didn’t mention social media. She underscored that while traditional infrastructure in Nigeria and other countries may be lacking, everyone has a cell phone and electronic communication is crucial to how they live their lives. It seemed out of touch not to acknowledge that reality of life in her fiction.

 

Carolina de Robertis spoke next about her novel, but my favorite quote by her came from the Q&A after the moderated panel concluded, which was that “Culture is not static; we can shift culture and push it open with the narratives that we live and write.”

Pajtim Statovci spoke last about his novel, and addressing the fact that living through the trauma of immigration, especially as a refugee, doesn’t automatically make you stronger.

Sometimes our negative experiences don’t make us stronger. Sometimes they make us weaker and sad and pathetic.

That resonated with me, because it’s easy to look at those who have survived something traumatic and assign strength to them merely because they survived. But that isn’t always the case. This thread resonated with the other books on the panel as well, because the main character in Khadivi’s book is an immigrant who radicalizes after immigration. Lesley Nneka Arimah mentioned about wanting to write about flawed characters as well, in the vein that we often think of ourselves as better than we are, so she wanted to write about characters that do the wrong thing in service of finding their own truth.

Overall impressions

The festival was worth my time to attend, and spend time thinking and talking about books with and around other book-minded people. I look forward to the next year’s book festival and the sessions! It’s always easy to attend when it’s convenient to get to and the weather is beautiful. Now I’m inspired to tackle even more of the books on my shelves…

 

Accessibility, Sound, and Communication

My birthday was yesterday! To celebrate, I ate an overly large and overly expensive steak and sorely undercooked brussels sprouts. Do yourself a favor and always roast brussels sprouts until they are caramelized and crunchy, then put some reduced apple cider and maple syrup on top. YUM!


Technology, while making the world more accessible than it has been in the past, has a lot of work to do for people with disabilities. A huge example of this is the shortcomings in OCR (optical character recognition) technology. In short, OCR sucks. And when we use it to simplify our lives (make a PDF into something that I can copy-paste into a text file), then when it fails it’s a minor inconvenience, and a silly one at that.

Just one problem. Continue reading

So This Is The New Year

I didn’t start this as a resolution post, but here we are. It’s easier to write the introduction after the essay is written, so here I am to tell you this is a post of my 2015 resolutions. This year is all about purging the “someday maybes” and turning ideas into actions. Taking care of myself and moving forward.

Continue reading

Reading, Drones, and Georgie Washington

Americans are still reading books, Internet and all! Younger Americans are actually reading more than older generations, which could be partially due to the fact that with the rise of texting and social media, so much of our communication is text-based, so everyone is doing a lot more reading (and writing) in order to communicate with their friends. The original study is linked in that article and in this graph:

What are some other ways to get people to read books?

Well it helps a lot if your college library not only tells you the call numbers of the book, but it gives you precise directions to the location of the book, which is pretty awesome. Much more useful when navigating a giant library, like I have access to at the university I work at, as opposed to the smaller library at the university I actually attended.

Continue reading

Parks, America, and Reading

It’s Thursday! Not Friday. Go to work tomorrow. When you don’t have to work, though, you can go outdoors! Because July is Park and Recreation month. So. If you’re not working, and it is nice outside, go outside. Weekend, planned. Just for you.

Bruce is a jungle dog.

National parks are a great place to go outdoors. The National Parks Conservation Association is taking care to recognize people who identify as LGBT+ by doing more to preserve historical locations important to the legacy of LGBT+ life in the United States. More national parks, more important history preserved, lives validated. Recognized.

Mostly white people visit national parks. Fact. As of 2011, “only 7 percent of visitors to the parks system were black.” It hasn’t always been this way. The Boston Globe interviews geographer Carolyn Finney, who is recapturing the role of African-Americans in the history of the national parks system and the environmentalist movement.

Continue reading

Journalism, Networks, and Grief

Here’s what was important this week….

Felix Salmon, a formers Reuters journalist, wrote a screed about why publishing news with the readers in mind is more valuable than breaking news.

As he puts it, “when journalists start caring about scoops and exclusives, that’s a clear sign that they’re publishing mainly for the benefit of other journalists, rather than for their readers. “

Even more clearly, and something that I can relate to easily, is the idea that:

“Readers come first, and all decent publications have their own readership: they shouldn’t be so meek as to assume that their readers will have invariably found the same news elsewhere, just because someone else’s version arrived a little earlier.”

When you spend most of your time on the Internet surrounded by, to borrow his phrase, media navel-gazers who lives on Twitter, everything starts to seem like unimportant, old news. But thankfully, when you talk to others outside of that arena, it is easy to remember that news that seems everywhere and overdone in one circle could be totally absent in another.

Continue reading

Women, the Web, and the App Takeover

Here’s what was important this week…

Today is Pi day. Here is more than you probably ever wanted to know about pi day.

Last Saturday, March 8 was International Women’s Day. Started as a revolutionary holiday to honor the achievements of women, International Women’s Day is recognized in many countries. However, in Nepal it is recognized by women only, rather than as a day where men pay tribute to the women. Nepal also has another holiday that only women observe:

“In early September in Nepal, Hindus – who make up 81 per cent of the country’s 30.5 million people – celebrate Rishi Panchami, a festival that commemorates a woman who was reborn as a prostitute because she didn’t follow menstrual restrictions. It is a women’s holiday, and so Nepal’s government gives all women a day off work. This is not to recognise the work done by women, but to give them the time to perform rituals that will atone for any sins they may have committed while menstruating in the previous year. (Girls who have not begun menstruating and women who have ceased to menstruate are exempt.)”

However, the interesting thing about a cultural distaste and monthly banishment that occurs surrounding menstruation, is that “they talk openly – more openly perhaps than the average teenage girl in the UK might – about what they use for sanitary protection. Some use sanitary pads, some are happy with cloths, although they dry them by hiding them under other clothes on washing lines.”

Continue reading

What is Old is New Again

Facebook has named its new app offering, which debuted today, “Paper”. As Lev Manovich points out, this naming signifies that “Old media metaphors are not going away” In fact, old media themselves aren’t going away.

Nowadays, fears that e-books and mp3s will dominate the reading and listening landscapes are all over the media. These fears seem somewhat cyclical, with the same old complaints cropping up decade after decade, as documented by the NYTimes more than once, Tom Standage in Wired, and XKCD, among others. Fear of the new manifests itself as dismissal of the digital, or whatever new technology has come to the fore.

Research has proven that not only do books have some staying power, old forms of music media are regaining popularity as well. Millenials are buying more books than other generations, and vinyl records are making a comeback. Cassette tapes, even, have found a resurgence.

Continue reading

Design, Destruction, and Reading

Here’s what was important this week…

As the web and technology become ever more ingrained in our day to day lives, the role of designers becomes more apparent. Designers have been around since things began to be created, and according to one man, they’ve destroyed the world.

It’s a bold statement. But designers (architects, if you’re a designer of buildings and structures) have designed prisons, and even the solitary housing units (SHUs) that unconstitutionally detain inmates.

Mike Monteiro wants to change that. In his 45 minute long talk (it’s worth it, though I admit my attention was wavering at the 40 minute mark), he passionately declares that it is the responsibility of all designers to be gatekeepers for bad, and outright harmful, design. And he has a point. If something isn’t designed, it can’t be built (or at least, not very well). He calls on designers to recognize the power that they have, even if they don’t realize it.

Continue reading