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

So you want to be a technical writer

If you’re interested in becoming a technical writer, or are new to the field and want to deepen your skills and awareness of the field, this blog post is for you.

What do technical writers actually do?

Technical writers can do a lot of different things! People in technical writing write how-to documentation, craft API reference documentation, create tutorials, even provide user-facing text strings to engineers.

Ultimately, technical writers:

  • Research to learn more about what they are documenting.
  • Perform testing to verify that their documentation is accurate and validate assumptions about the product.
  • Write words that help readers achieve specific learning objectives and that capture what the writer has learned in the research and testing processes.
  • Initiate reviews with engineers, product managers, user experience designers, quality assurance testers, and others to validate the accuracy, relevancy, and utility of the content.
  • Advocate for the customer or whoever uses the product or service being documented.

The people reading what technical writers have produced could be using software they’ve purchased from your company, evaluating a product or service they are considering purchasing, undergoing a required process controlled by your organization, writing code that interfaces with your services, configuring or installing modifying hardware produced by your company, or even reviewing the documentation for compliance and certification purposes. Your goal, if you choose to accept it, is to help them get the information they need and get back to work as soon as possible.

Identify what you want from your career

Some general career-assessment tips:

  • Identify what motivates you and what challenges you.
  • Identify what type of team environment you want. These are loose descriptions of types of team environments that are out there:
    • A large highly-collaborative team with lots of interaction
    • A distributed team that is available for questions and brainstorming as needed, but largely everyone is working on their own thing.
    • A small team that collaborates as needed.
    • A team of one, it’s just you, you are the team.

Is technical writing a good fit for you?

  • Do you enjoy explaining things to other people?
  • Do people frequently ask you to help explain something to them?
  • Do people frequently ask you to help them revise content for them?
  • Do you care or enjoy thinking about how to communicate information?
  • Do you identify when things are inconsistent or unclear and ask people to fix it? (Such as in a UI implementation, or when reviewing a pull request)
  • Do you enjoy problem-solving and communication?
  • Do you like synthesizing information from disparate sources, from people to product to code to internal documentation?
  • Do you enjoy writing?

My background and introduction to technical writing

I started in technical support. In college I worked in desktop support for the university, wandering around campus or in the IT shop, repairing printers, recovering data from dying hard drives, running virus scans, and updating software. After graduation I eventually found a temp job working phone support with University of Michigan, managing to turn that position into a full-time permanent role and taking on two different queues of calls and emails. However, after a year I realized that was super exhausting to me. I couldn’t handle being “on” all day, and I found myself enjoying writing the knowledge base articles that would record solutions for common customer calls. I wrote fifty of them by the time I discovered a posting for an associate-level documentation specialist.

I managed to get that position, and transferred over to work with a fantastic mentor that taught me a ton about writing and communicating. After a few years in that position, writing everything from communication plans (and the accompanying communications), technical documentation, as well as a couple video scripts, I chose to move to California. With that came another set of job hunting, and realizing that there are a lot of different job titles that technical writing can fall under: UI writer, UI copywriter, technical writer, documentation specialist, information developer… I set up job alerts, and ended up applying, interviewing, and accepting an offer for a technical writing position at Splunk. I’ve been at Splunk for several years now, and recently returned to the documentation team after spending nearly a year working in product management.

Where people commonly go to technical writing from

Technical writers can get their start anywhere! Some people become technical writers right out of college, but others transition to it after their career has already begun.

As a technical writer, your college degrees doesn’t need to be in technical writing, or even a technical-specific or writing-specific field. I studied international studies, and I’ve worked with colleagues that have studied astronomy, music, or statistics. Others have computer science or technical communication degrees, but it’s not a requirement.

For people transitioning from other careers, here are some common starting careers:

  • Software developers
  • UX practitioners
  • Technical support

That’s obviously a short list, but again if you care about the user and communication in your current role, that background will help you immensely in a technical writing position.

Prepare for a technical writing interview

Prepare a portfolio of writing samples

Every hiring manager wants to see a collection of writing samples that demonstrate how you write. If you don’t work in technical writing yet, you might not have any. Instead, you can use:

  • Contributions you’ve made to open source project documentation. For example, commits to update a README: https://github.com/yahoo/gryffin/pull/1
  • How-to processes you’ve written. For example, instructions for performing a code review or a design review.
  • A blog post about a technical topic that you are familiar with. For example, a post about a newly-discovered functionality in CSS.
  • Basic task documentation about software that you use. For example, write up a sample task for how to create a greeting card in Hallmark Card Studio.

Your portfolio of writing samples demonstrates to hiring managers that you have writing skills, but also that you consider how you organize content, how you write for a specific audience, and the level of detail that you include based on that audience. The samples that you use don’t have to be hosted on a personal website and branded accordingly. The important thing is to have something to show to hiring managers.

Depending on the interviewer, you might perform a writing exercise in-person or as part of the screening process. If you don’t have examples of writing like this, that’s a good reason to track down some open source projects in need of some documentation assistance!

Learn about the organization and documentation

Going in to the interview, make sure you are familiar with the organization and its documentation.

  • Read up about the organization or company that you are interviewing with. If you can, track down a mission statement for the organization.
  • Find the different types of documentation available online, if possible, and read through it to get a feel for what the team might be publishing.
  • If the organization provides a service or product that you’re able to start using right away, do that!

All of these steps help you better understand how the organization works, what the team you might be working on is producing, and demonstrates to the interviewer that you are motivated to understand what the role and the organization are about. Not to mention, this makes it clear that you have some of the necessary skills a technical writer needs when it comes to information-gathering.

Questions you might want to ask

Find out some basic team characteristics:

  • How many other technical writers are at the organization?
  • What org are the technical writers part of?
  • Is there a central documentation team or are the writers scattered across the organization?
  • How distributed is the documentation team and/or the employees at the organization?

Learn about the documentation process and structure:

  • What does the information-development process look like for the documentation? Does it follow semi-Agile methods and get written and researched as part of the development team, or does information creation follow a more waterfall style, where writers are delivered a finished product and expected to document it? Or is it something else entirely?
  • Are there editors or a style guide?
  • Do the writers work directly with the teams developing the product or service?
  • What sort of content management system (CMS) is in use? Is it structured authoring? A static-site generator reliant on documentation files written in markdown stored next to the code? A wiki? Something else?

Find out how valuable documentation is to the organization:

  • Do engineers consider documentation vital to the success of the product or service?
  • Do product managers?
  • Do you get customer feedback about your documentation?
  • What is the goal of documentation for the organization?

Some resources for getting started with technical writing

Books to read

These books cover technical writing principles, as well as user design principles. None of these links are affiliate links, and the proceeds of the book I helped author go to charity.

  • The Product is Docs by Christopher Gales and the Splunk documentation team
    • Yes, I helped.
  • Every Page is Page One by Mark Baker
    • This book is a great introduction and framework for writing documentation for the web.
  • Developing Quality Technical Information by Michelle Carey, Moira McFadden Lanyi, Deirdre Longo, Eric Radzinski, Shannon Rouiller, and Elizabeth Wilde.
    • This book is a great resource and reference for detailed writing guidance, as well as information architecture.
  • Design of Everyday Things by Don Norman
    • The classic design book covers user-focused principles that are crucial to writing good documentation.

This is an intentionally short list featuring books I’ve found especially useful. You can also consider reading Scenario-Focused Engineering: A toolbox for innovation and customer-centricity, Nicely Said: Writing for the Web with Style and Purpose, Content Everywhere: Strategy and Structure for Future-Ready Content, Design for How People Learn, and Made to Stick: Why Some Ideas Survive and Others Die.

Articles and blogs about technical writing

I like following resources in RSS feeds to get introduced to good thinking about technical writing, but not all good content is new content! Some great articles that have helped me a lot:

Blogs to follow (intermittently updated)

Great articles about technical writing

Other web resources

Twitter is a great resource for building a network of people that care about documentation. If you use it, I recommend searching for people who commonly tweet with #writethedocs.

Write the Docs is a conference and community founded by Eric Holscher and maintained by a brilliant set of volunteers!

The Write the Docs Slack workspace is fairly active, and includes channels for job postings, career advice, as well as current discussions about trends and challenges in the technical writing world.

Some talks from the conference I recommend checking out are visible on YouTube:

There are playlists for 2018 (which I did not attend) and earlier years as well on YouTube, so dig around there and find some more resources too if watching videos is useful to you!

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…

 

#tweetthedocs: Use Twitter to meet your users where they are

As a tech writer, it’s hard to tell how users get to your docs at all. They might be clicking on in-product help links, searching the web, or getting sent links from support. But you can get proactive about it too. Help users of your product get their questions answered by meeting them where they are—on social media sites like Twitter. You may already rely on marketing, sales, support, and search engines to bring users to your documentation, but social media is a direct option. You can tweet about anything from general topics that answer common user questions to drier topics that are important for people to know. Read on to learn how!

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

Misogyny, Maya Angelou, and Words

A lot has happened since last week.  As a heads up, the first portion of this post is about misogyny and the UCSB shootings last weekend. If you’d rather not read about it, skip below the comic!

Last weekend, a man murdered 6 people and injured 13 more. Misogyny is largely being credited (not much in mainstream media, however) as the primary driver behind his violence. The killer left behind several youtube videos and more than a hundred pages of a violent manifesto. His parents had reached out to his therapist, and the police met with him, but nothing came of the meeting. Part of this is because they based their judgment of him on their face-to-face interaction, rather than on his digital droppings of his thoughts and opinions, perhaps a misprioritization in our current world.

As I’ve written before, there is a real risk in defining people based solely on what they post on social media. But when so much of someone’s thoughts and feelings are revealed online, their narrative becomes more transparent. This man’s narrative was one of violent, extremist misogyny.

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

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