Tackling Technical Writing

by Alaina Kafkes

In the talk titled Tackling Technical Writing, presented at RubyConf AU 2018 by Alaina Kafkes, the speaker delves into the significance of technical writing within the tech community, particularly in the Ruby ecosystem. Kafkes emphasizes that technical writing is essential for creating accessible and empathetic documentation, which benefits both newcomers and seasoned members of the Ruby community. The session addresses common mental barriers like fear, uncertainty, and indifference that hinder individuals from contributing to technical writing.

Key Points Discussed:
- Understanding Technical Writing: Technical writing is broadly defined as writing about technology and is a skill that everyone can learn and utilize.
- Overcoming Mental Blockers: Kafkes discusses the need to confront fears associated with writing. Rather than fearing mistakes, individuals should focus on sharing their unique perspectives and experiences.
- The Technical Writing Process: Kafkes outlines five phases of technical writing: brainstorming, writing, honing, publishing, and reflecting, providing ten tips to enhance writing skills, including:
- Brainstorming: Encourage writing about personal solutions to technical problems and broaden topics beyond code.
- Writing: Organize content using headers and incorporate visuals to enhance understanding.
- Honing: Seek feedback from peers and adopt the reader's perspective to ensure clarity.
- Publishing: Utilize popular platforms for dissemination and include calls to action to engage readers.
- Reflecting: Be open to feedback and maintain consistency in writing to build an audience.
- Practical Activity: The session includes an interactive segment inviting attendees to jot down writing ideas, fostering immediate engagement with the concepts discussed.
- Closing Thoughts: Kafkes concludes with an emphasis on continuous sharing and the importance of community support in technical writing, encouraging individuals to embrace their voices and contribute meaningfully.

This talk serves as both a motivational and practical guide to improving technical writing skills within the tech community, illustrating the broader narrative that effective communication is vital for progress.

00:00:05.720 Hello everyone! As I mentioned, I am Alaina Kafkes and this session is about tackling technical writing, which I find super exciting. I work at a US-based company called Media, a platform where many people write blogs. I also consider myself a writer with experience in both technical writing and personal, non-technical writing. Additionally, I think of myself as a logophile, which is a fancy way of saying I love words. I was excited to learn some new vocabulary yesterday and I'm thrilled to be at this tech conference. Throughout this talk, please feel free to say hi, provide feedback, or ask questions on Twitter. You can find my handle right here and at the bottom corner of all my slides.

00:01:00.989 To begin, I'll be discussing technical writing. Technical writing can be defined simply as writing about technology. Anyone is capable of doing technical writing, and our industry truly needs accessible, empathetic, and thorough documentation. This is not only necessary within our industry, but also within the Ruby community. Both newcomers and veterans can develop their skills by reading well-crafted technical writing from authors with diverse perspectives.

00:01:14.820 Best practices and Ruby's standards are communicated effectively through writing. However, there's an issue: many people in tech shy away from writing, even though it's incredibly important. Why is that? Often, people turn away due to fear, uncertainty, or indifference—these are significant mental blockers that prevent us from contributing to the written resources of the Ruby community. It's time to confront these blockers.

00:01:29.310 First, why let fear hold you back? It's normal to feel apprehensive about writing something incorrect or unhelpful. We all want to produce our best work, but sometimes, it's better to hit publish than to agonize over those fears and doubts for months. Additionally, why feel uncertain when technical writing can enhance your career prospects? Documenting your knowledge and sharing it with others in the Ruby community can bolster your reputation, expand your network, and even lead to job opportunities and speaking engagements.

00:02:12.870 Moreover, why feel indifferent when the future of our industry is at stake? The technical writing produced today will benefit those who join the Ruby community tomorrow. In the early days of technology, information was often arcane and inaccessible. Now, many of us are advocating for more inclusivity and accessibility in tech writing. It's our duty to create technical documentation that supports individuals from diverse backgrounds entering the Ruby community.

00:02:29.260 Now that I've shared why technical writing is important, the big question is: how do you produce high-quality technical writing? As a paid freelance technical writer, I can share my process with you. The technical writing process can be broken down into five distinct phases: brainstorming, writing, honing, publishing, and reflecting. In this talk, I will provide you with ten tips to enhance your technical writing abilities, with two tips for each phase of the writing process. For each tip, I'll discuss a common mental blocker and provide a reality check to debunk that blocker. This is my way of helping you overcome any remaining fears, uncertainties, and indifference towards writing.

00:04:06.820 Let’s get started. The first phase of the technical writing process is brainstorming. Brainstorming occurs before you start writing, focusing on generating ideas and topics to write about. My first tip is to write about how you solved a technical problem. Some of you may be thinking, 'I have nothing to write about; I'm no expert.' Can I see a quick show of hands if you've felt this way before? It's completely relatable. The reality is you don't need to be an expert to write—you just need to share your experiences, interests, and lessons learned.

00:04:38.600 Even if someone has already written a blog post on a Ruby topic you're passionate about, your perspective is still valuable. What makes your insights unique is you! My second tip for brainstorming is to not feel pressured to only write about code. Some of you might think you can't teach coding while you’re still learning. However, reading about code is just one aspect of technical writing; it encompasses anything related to technology. This includes discussions about the tech industry, community, and much more.

00:05:20.160 The second phase of the technical writing process is, unexpectedly, writing itself. Writing is when you sit at your computer and start to draft your ideas. My first tip for the writing phase is to break things down into steps or sections. This approach is useful if you feel your writing is disjointed. Can I see another show of hands for those who lack confidence in their writing abilities? A little organization can greatly enhance the clarity of your writing.

00:05:59.930 Something I like to do is write headers for various sections in my blog post before drafting the entire piece. This practice allows me to plan ahead and define the direction my writing will take. Once my blog is complete, the reader will benefit from a clear understanding of the agenda, which attracts the right audience who will find value in your work. My second tip is to include images, diagrams, hyperlinks, or any media that complements your writing. This is especially beneficial if your explanations tend to be lengthy.

00:06:43.750 The reality check here is that it’s challenging to keep readers engaged with only text. Illustrating technical concepts through visuals like diagrams, sketches, gifs, or actual code snippets can often convey ideas more concisely than words alone. Additionally, incorporating links that invite readers to 'learn more' can be much more effective than diverging into lengthy tangents. While I advocate for writing, I also believe individuals should embrace non-traditional formats for expressing their ideas, such as sketchnoting, filmmaking, or podcasting. Choose whatever medium best fits your message.

00:07:33.480 The third phase of the technical writing process is honing, which encompasses the editing stage. My first tip for honing is to ask friends to review your writing. This tip is especially helpful for those who may feel self-conscious about their writing. I would like another show of hands—does anyone here feel self-conscious about their writing skills? Even the best writers seek feedback and proofreading assistance. It's beneficial to gather insights from friends with varying familiarity with your subject—some who grasp the topic well and others who may be complete beginners.

00:08:03.690 Once you publish your blog post, it's likely to be read by people from diverse backgrounds. Receiving feedback from friends with different perspectives helps you identify potential weaknesses in your writing, allowing you to correct them before publication. Also, when you ask friends or coworkers for help, remember to acknowledge them in your article. This is a thoughtful way to show appreciation and demonstrate to future writers that writing is a collaborative effort.

00:08:52.270 My second tip for the honing phase is to be the reader. Some of you may fear that your writing won’t make sense. The best way to combat this fear is to place yourself in your reader's shoes. Earlier this year, I did some freelance writing for Twilio, a conference sponsor, where I learned valuable techniques related to voice and technical reviews. A voice review involves reading your blog post aloud and editing whenever you encounter confusion. Hearing your words can often reveal if you've expressed something awkwardly. For tutorials that incorporate code, there's another technique called the technical review—code alongside your tutorial to verify you're achieving the desired result.

00:09:54.400 This method is particularly advantageous because one of the most frustrating aspects of following a tutorial is encountering errors without understanding them. For those of you who are experienced software engineers, handling these errors may be straightforward, but for newcomers, decoding such errors can be daunting. By anticipating points where beginners may stumble and patching them up before publication, you can ensure they remain engaged and successful as they navigate your blog.

00:10:31.650 The fourth phase of technical writing is publishing, which involves clicking that publish button to make your work live. However, I believe it’s equally crucial to consider the concept of publicizing. Publicizing encompasses the marketing and sharing of your writing to reach a wider audience. Therefore, I recommend combining these two actions. Upon publishing an article, immediately move to publicize it.

00:11:12.040 One tip for publishing is to leverage popular technical writing platforms. If you're concerned that no one will read or benefit from your writing, you're not alone. I remember feeling paralyzed before publishing my first piece online, thinking it would be useless. The reality is you can approach gaining readership strategically. The first step is to share your writing with friends and family, which may be less intimidating than broadcasting it directly on social media. Don’t hesitate to promote your work publicly.

00:11:46.210 If you aim to expand your readership beyond your immediate network, consider utilizing platforms like Medium, which hosts high-traffic publications such as Free Code Camp, Hacker Noon, and Code Like a Girl. These publications have large followings and provide marketing support—they often promote your articles via tweets and newsletters, getting your work in front of more eyes than you could achieve alone. Another fantastic platform known for its developer community and social media marketing is Dev.to.

00:12:36.150 The second tip for publishing is to include a call to action at the end of your article. This tip helps if you're worried that no one will interact with your writing. The power of suggestion carries significant weight; consider adding a footer containing your contact information, such as your email address or Twitter handle, and a statement that invites readers to engage with you after reading. For instance, you could encourage them to like or share your content or to reach out with their thoughts or questions.

00:13:21.670 The fifth and final phase of technical writing is reflecting—a step often perceived as extra but incredibly valuable for staying engaged with your writing and planning future projects. One tip for reflecting is to be receptive to respectful comments. Have you ever felt apprehensive about receiving negative feedback online? I certainly have. The truth is, I often fear unpleasant notifications from platforms like Medium or Dev.to, but it's important to recognize that everyone's experiences are different.

00:14:28.360 When faced with criticism, your best strategy is either to ignore it or respond with kindness. For constructive feedback, acknowledge it and respond to the person, even with a simple thank you. This personal touch can foster a sense of connection with your audience and encourage them to continue engaging with your work. Additionally, striving for consistency in your writing can help you build a following. If you set a weekly or monthly writing goal, publicizing your content when it’s released will attract and retain your readers.

00:15:28.320 It’s essential to remember that no reader will invest in your work if consistency is lacking. So, those are the ten tips that will help you tackle technical writing! Like any worthy technical writer, I can’t let you go without a call to action before offering you a break for afternoon tea.

00:16:10.370 Now, it’s activity time! If you could take out a sheet of paper, your phone, a laptop, or anything on which to write, please take about 30 seconds to jot down something you'd like to write about. I'm sure I’ve sparked some ideas during my talk, so let’s start the timer for 30 seconds.

00:16:59.520 Finish up your thoughts if you'd like, but I'll continue with this lovely talk. Ideally, you’ve captured an excellent idea on your writing medium. When you leave this conference, I encourage you to follow my tips and go write that blog post you’ve been dreaming about. If you need an incentive, tweet your published work to me, and I will retweet it, helping you reach a broader audience.

00:17:22.080 Before we wrap up, I want to share my favorite Vonnegut quote that inspires me to write: 'To practice an art, no matter how well or badly, is to make your soul.' Remember that you’re interested enough in this talk, in the Ruby community, and in improving your technical writing. So go ahead, write, and share your voice. Thank you!

00:18:08.950 I appreciate you all for listening to this insightful technical writing talk. Please feel free to connect with me on Twitter to share your thoughts, comments, or any ideas you gather from my talk. You can also find my presentation slides through the bitly link provided. If we have any time left, I'd be more than happy to answer any questions you might have.

00:18:50.220 Now, does anyone have thoughts on when it’s most beneficial to write during your learning journey for the benefit of others? That’s a great question! I personally am pretty new to the tech industry, being just six months into my first job, so I can’t speak to future experiences. However, I believe all phases of learning are valuable. Whenever you're approaching something new, writing about it can solidify your own understanding while sharing that knowledge with others.

00:19:39.480 Are there any more senior engineers who would like to share their perspectives? I’d love to hear what you think! Thank you!

00:21:00.100 This is indeed an excellent question. Personally, I often hesitate to publish something that is highly vulnerable; while there are certainly things that I prefer to keep private, I find that the more I publish, the more open and willing I become to expose my vulnerabilities in my writing.

00:21:48.620 I believe that with experience, you're naturally inclined to be more open about your thoughts and ideas. So, the more you publish, the more comfortable you may feel with vulnerability. That said, it's essential to maintain boundaries and protect your personal feelings.

00:22:58.580 The question remains: How can we improve the tech community and online environment to ensure that writers feel safe sharing their insights without fear of vitriol? For instance, Medium's recent decision to update its terms of service to ban harmful behavior, both on and off the platform, is a step in the right direction. It’s encouraging. And tackling behavior across platforms can help mitigate toxicity in online communities.

00:23:28.480 While freedom of speech is vital, finding a balance between restricting toxic behavior and maintaining open expression can be challenging. We must engage in healthy conversations about how to create safer spaces online for absent voices.

00:24:05.360 It's crucial that we foster an environment where people can share ideas without fear. For those experiencing negativity, it’s okay to seek support by having someone else screen your interactions on social media in high-pressure situations.

00:25:01.380 Additionally, I encourage making use of anonymity when discussing sensitive topics, like how one engineer used it to express their thoughts without fear of backlash. It's about creating safe spaces and, importantly, being there for one another.

00:26:36.000 I think it’s essential that we continually strive to improve the community and what condition we can set for its growth. We all have a responsibility to uplift each other and create spaces free from toxicity.

00:27:39.230 I’d like to share a point on how sarcasm can can often be misinterpreted online, particularly in technical writing. The tone isn’t always conveyed as intended in written formats.

00:28:15.040 Maintaining clarity is key while ensuring we provide our readers with kindness and understanding. Technology can be challenging enough; we shouldn’t make the learning curve harder on others.

00:29:38.360 For those of you who have no particular tech stakeholders in your writing, is it better to call attention to bad design choices when the actual creators could read your work? It's often about how you frame the situation. Emphasizing design decisions made with intention, even if they didn't pan out well, can show growth. It’s perfectly okay to share knowledge while remaining respectful.

00:30:37.320 Ultimately, by adopting a positive and constructive approach in our critiques, we encourage growth and learning within the community.

00:31:03.480 I appreciate all the great discussions today, and I thank you all for your participation.

RubyConf AU 2018