<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:media="http://search.yahoo.com/mrss/"><channel><title><![CDATA[Everything Technical Writing]]></title><description><![CDATA[Your One Stop Blog For All Things Technical Writing and Technical Content Creation]]></description><link>https://www.everythingtechnicalwriting.com/</link><image><url>https://www.everythingtechnicalwriting.com/favicon.png</url><title>Everything Technical Writing</title><link>https://www.everythingtechnicalwriting.com/</link></image><generator>Ghost 2.9</generator><lastBuildDate>Tue, 18 Feb 2025 13:37:28 GMT</lastBuildDate><atom:link href="https://www.everythingtechnicalwriting.com/rss/" rel="self" type="application/rss+xml"/><ttl>60</ttl><item><title><![CDATA[SEO is sinking ship. Swim or Drown?]]></title><description><![CDATA[If your team has been discussing what it means to do content marketing in the age of AI, send them this piece.]]></description><link>https://www.everythingtechnicalwriting.com/seo-is-sinking-ship-swim-or-drown/</link><guid isPermaLink="false">Ghost__Post__67b4857f3a9f46001bc1219d</guid><category><![CDATA[Content Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Tue, 18 Feb 2025 13:32:33 GMT</pubDate><media:content url="https://res-5.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Heading.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-5.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Heading.png" alt="SEO is sinking ship. Swim or Drown?"/><p>A few years ago, Google was the go-to for almost every online search. That’s changing. People now turn to AI tools like ChatGPT and Perplexity for quick, aggregated answers. Alternatively, they go to communities on Reddit, LinkedIn, TikTok, and Instagram for personal recommendations.</p><p>If your content strategy still revolves around ranking in SERPs for top-of-funnel keywords, you might be chasing a shrinking opportunity.</p><p>A year ago, if I wanted to understand a specific technology, say, “edge computing?” or “SQL partitioning?”—I’d go to Google, sift through results, and hope to find an article that wasn’t just fluff stuffed with keywords, and clearly explains the concepts to my understanding..</p><p>Now? My first stop is ChatGPT. I ask questions as I would to a teacher, refine my query, and get a direct, well-structured explanation—without ever clicking a website. Companies like <strong>PlanetScale</strong> or <strong>Fly.io</strong> that may have spent time and effort ranking for these search terms might never see me on their site because I no longer need to use search.</p><p>Just last week, while trying to show a friend a cool new tool I had found, I grabbed his laptop, opened a new tab, and to my surprise he set his browser was set to load the ChatGPT homepage instead of Google for every new tab. He told me he hadn’t used Google Search in months. And I know he’s not the only engineer with a setup like this.</p><p>Even when people do use Google, <strong>60% of searches now end without a single click</strong>, according to an <a href="https://sparktoro.com/blog/2024-zero-click-search-study-for-every-1000-us-google-searches-only-374-clicks-go-to-the-open-web-in-the-eu-its-360/">analysis by Rand Fishkin of SparkToro</a>. Search for anything today on Google search, and here’s how the results typically appear:</p><ul><li>At the very top, AI-generated answers,</li><li>Then, paid search results,</li><li>Then, the <strong>People Also Ask</strong> section,</li><li>And finally, <strong>organic search results</strong>—the content brands have spent time writing and optimizing—buried beneath all of that.</li></ul><p>Google has taken a page from social media platforms like X by designing search to keep users inside its ecosystem. What used to be prime real estate for publishers is now increasingly being taken over by Google’s own services.</p><p>If your team has been discussing what it means to do <strong>content marketing in the age of AI</strong>, send them this piece.</p><p>While the examples I use here are software-engineering-focused because I’m a developer advocate, this shift in search behavior affects every industry. The way people find and engage with content is changing. Let’s talk about what that means, and what to do about it.</p><h2 id="top-of-funnel-seo-is-losing-relevance-google%E2%80%99s-changing-landscape-and-the-zero-click-problem"><strong>Top-of-Funnel SEO Is Losing Relevance: Google’s Changing Landscape and the Zero-Click Problem</strong></h2><p>Like I said, if you’re still pouring resources into ranking for broad informational keywords, it might be time to <strong>rethink your TOFU strategy</strong>.</p><p>In <a href="https://sparktoro.com/blog/new-research-we-analyzed-332-million-queries-over-21-months-to-uncover-never-before-published-data-on-how-people-use-google">another brilliant research report from SparkToro’s Rand Fishkin</a>, 332 million Google searches from 130,000 U.S. devices were analysed over 21 months (Jan 2023 – Sept 2024) and found that <strong>51.7% of searches are informational.</strong></p><p>This isn’t surprising.</p><p>Informational searches have always made up the largest share of queries, which is why TOFU content has been a core pillar of SEO-driven content strategies for brand awareness.</p><p>At the TOFU stage, users aren’t looking for a specific product or company. They’re in research mode, trying to understand a topic or problem. They want definitions, explanations, and high-level guides. At this stage, searches would be things like:</p><ul><li><em>“What is Zero Trust security?”</em></li><li><em>“How does edge computing work?”</em></li><li><em>“What is database sharding vs. partitioning?”</em></li></ul><p>For years, brands have been using TOFU content to capture potential customers early, educate them, and subtly introduce their product or service. But that strategy is losing effectiveness, not because people are searching less, but because Google is making sure they don’t need to click away to get answers.</p><p><strong><em>To reiterate, 60% of informational searches now result in zero clicks</em>.</strong> That means for every 1,000 searches, only <em><strong>360 clicks make it to a non-Google-owned, non-ad-paying website.</strong></em></p><p>This isn’t accidental. It’s by design.</p><p>Users now expect a single, definitive answer rather than sifting through countless search results. AI tools like ChatGPT and Perplexity have trained them to value quick, summarized responses over deep dives. Google has recognized this shift and is quietly transforming from a search engine into an answer engine that keeps users on its platform instead of directing them to external sites.</p><p>In June 2024, Google introduced <em>Search Generative Experience (SGE)</em>, a new feature that places AI-generated summaries at the top of search results. These summaries pull information from multiple sources and remove the need for users to visit external websites.</p><p>As if that isn’t bad enough for SEO efforts, there have been rumours of <a href="https://searchengineland.com/google-search-testing-ai-mode-451672">Google Search making plans to roll out an 'AI Mode'</a> within Google Search that will look nearly identical to its Gemini AI chatbot. Instead of clicking on links, users will simply receive AI-generated answers right on the search page.</p><p>Over time, as AI-generated responses improve, <strong>even fewer users will browse through search results.</strong></p><p>For the <strong>40% of searches that do result in a click</strong>, the <a href="https://sparktoro.com/blog/new-research-we-analyzed-332-million-queries-over-21-months-to-uncover-never-before-published-data-on-how-people-use-google/">data shows</a> they’re largely <strong>branded or navigational</strong>:</p><ul><li>44% of Google searches are branded, meaning users already know the platform or website they want to visit and use search as a shortcut. The top searched terms include <em>YouTube, Gmail, Amazon, ChatGPT, WhatsApp Web, and Instagram.</em></li><li>33.1% are navigational, e.g <em>“AWS documentation”</em> or <em>“<a href="http://Fly.io">Fly.io</a> pricing.”</em></li><li>14.5% have commercial intent, e.g <em>“Tailscale vs. ZeroTier”</em> or <em>“SOC 2-compliant Zero Trust platforms.”</em></li><li>Only 0.69% are transactional, indicating direct purchase intent.</li></ul><p>What this tells us is clear. By the time someone searches on Google now, they’ve already been influenced elsewhere. The awareness and consideration happened on another platform, perhaps through social media, AI-driven recommendations, or community discussions.</p><p>Google is slowly evolving from discovery engine to an endpoint for users who have already made up their minds. If you want to be part of their decision-making process, you need to be where the awareness actually happens. That means looking beyond search engines and focusing on the platforms where your audience actively engages, learns, and discusses the topics you’re covering.</p><h2 id="how-to-adapt-to-imminent-search-behaviour-changes"><strong>How to adapt to imminent search behaviour changes</strong></h2><p>Let’s get one thing straight, this is not a call to abandon content creation or burn your SEO strategy to the ground. Content still matters, probably more than ever.  But <strong>what</strong> you create and <strong>how</strong> you distribute it needs a rethink.</p><p>If you create content in the technology space like I do, you should recognize that your audience are usually first adopters. They’re most likely ahead of this behaviour change. If they’re adapting, we should too.</p><p>Consider all the recent moonshot/disruptive inventions (ha, when you’re doing an MBA, you’re bound to pick up a few phrases like moonshot and disruptive) like Uber, Airbnb, Telsa, Space X, and co. They were initially met with a lot of skepticism but ended up changing consumer behaviour across travel, transportation, and ownership significantly.</p><p>The Industrial Revolution did the same. Before coal, wood was the primary fuel source. Feudal lords controlled wealth through land and agriculture. Then steam engines replaced manual labor, factories rose, and cities grew. The invention of cars and trains made it possible to live far from work, creating the world of commuting we know today.</p><p>The digital age is undergoing its own upheaval. AI is reshaping how people find information, and assuming that content discovery and consumption habits will remain unchanged is wishful thinking at best.</p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/image.png" class="kg-image" alt="SEO is sinking ship. Swim or Drown?" loading="lazy" width="1493" height="1193"><figcaption><em>Will ChatGPT now become the largest traffic referrer?</em></figcaption></img></figure><p><em>                      Will ChatGPT now become the largest traffic referrer?</em></p><p>Here’s what I think we should be doing to stay on top of these habit changes: </p><h3 id="1-prioritise-putting-your-content-where-your-customers-spend-time-organically"><strong>1. Prioritise putting your content where your customers spend time organically</strong></h3><p>If SEO isn’t the powerhouse it used to be, what should companies do instead? Simple: <strong>double down on content discovery and distribution.</strong> Find out <em>where your customers are and go there.</em></p><p>The thing is SEO or Search engines like Google and Bing have always been just one medium for content discovery. But because they dominated how people discovered information for so long, we ended up assigning them outsized importance, at the expense of other discovery channels.</p><p>However with all the data I’ve shared, you can agree with me that it’s no longer enough to publish content and wait for search engines to send traffic your way.</p><p><strong>Marcus Sheridan</strong>, author of <em>They Ask, You Answer</em> (one of my favourite books on content marketing), on <a href="https://www.socialmediaexaminer.com/creating-ai-avatars-how-to-create-video-clones-for-business/">a social media examiner podcast episode</a>, said that Google may see a <strong>25-40% decline in usage over the next decade.</strong> More importantly, for publishers and businesses, there could be a 70% decline in website visitors from search results.</p><p>You have to put your content where people already are. Places like:</p><ul><li>Social media &amp; professional networks (LinkedIn, Twitter/X, Reddit, Hacker News)</li><li>Community platforms (Dev.to, Hashnode, Medium, FreeCodeCamp)</li><li>Newsletters (both owned and through guest contributions)</li><li>Video &amp; short-form content (YouTube, TikTok, Instagram Reels)</li><li>Conferences?</li></ul><p>I like to put my money where my mouth is. That’s why <strong>content distribution and repurposing</strong> are at the top of the content strategy plan I wrote for my team in 2025. We’re approaching distribution as seriously as we approach production.</p><p>Here are two things we’ll be doing differently in our dev advocacy team:</p><p><strong>a. Content Distribution Wednesdays</strong>:</p><p>Since Wednesday at 8 AM is one of the best times to post on Hacker News, I’ve challenged my team to distribute or repurpose content weekly.</p><p>Every Wednesday, we’d mark off time on our calendars to take a piece from our content barn (preferably something fresh and relevant to a current campaign) and repurpose or distribute it on Reddit, Hacker News, LinkedIn, or X, both on personal pages and company channels. I’m in the process of automating this reminder for slack.</p><p><strong>b. Syndicating content to platforms with built-in distribution:</strong></p><p>Since we’re still on the topic of being where your audience are, developer-focused publishing platforms like Dev.to, Medium, Hashnode, and FreeCodeCamp already have huge engaged developer followings with built in distribution.</p><p>We’d be serious about syndicating content to one of those platforms or even making one our primary content source. I’ve even toyed with the idea of syndicating our email newsletter to a corresponding LinkedIn Newsletter. A couple of people in my network have found massive subscriber success with it, and it all boils down to built in distribution.</p><div class="kg-card kg-callout-card kg-callout-card-grey"><div class="kg-callout-emoji">🔇</div><div class="kg-callout-text"><em>My book on <b>Developer Advocacy for Individual Contributors</b> is almost here, and there’s a whole chapter on <b>distribution</b>—because what’s the point of great content if no one sees it?</em><br><br><em>Interested? <a href="https://everythingtechnicalwriting.substack.com/about">Drop your email</a>, and I’ll let you know when it drops. I’ll even send you the <b>first chapter for free</b> before anyone else.</em></br></br></div></div><h3 id="2-write-for-the-machines"><strong>2. Write for the machines?</strong></h3><p>Platforms like Perplexity already cite sources when surfacing AI-generated responses. If AI-driven discovery grows, companies may need to structure their content so that AI tools can accurately retrieve and reference their insights.</p><p>Lately, I’ve noticed utm <strong>referrals from ChatGPT</strong> showing up in our HubSpot marketing analytics reports.</p><p>Just two days ago, I found myself using ChatGPT for research I’d normally do on Google. I asked:</p><p><em>“What are the top 10 most popular SaaS apps that support IP allow lists and are widely used across enterprises?”</em></p><p>ChatGPT returned a list containing SalesForce, MicroSoft Azure, Okta, MongoDB Atlas, citing two pages from <a href="http://Bayansecurity.io">Bayansecurity.io</a> docs titled “<em>Secure Saas Applications with IP Allowlisting</em>” and “<em>Use IP Allowlisting to enforce zero trust policies for specific SaaS Applications integrated with Okta and Entra ID</em>” as it’s source**.** The list also included tools like Palo Alto, Rubric, OpenVPN and Sailpoint, citing doc pages of the respective tools on setting up or managing IP allowlists.</p><p>But here’s where things got interesting: It ranked Workday as #2, citing a GeekFlare blog titled <em>“Top 41 SaaS Companies Dominating the Market in 2025.”</em> The problem is, that blog never mentioned IP allowlisting at all.</p><p>Curious, I ran the same search on Google. Instead of surfacing relevant documentation, Google gave me generic “Top 10 SaaS platforms for businesses” articles, completely missing the nuance of what I was actually asking.</p><p>So, how do LLMs rank or surface web sources?</p><p>I don't know definitively. But one thing is clear: their ranking mechanisms are different from Google’s. That said, keywords still matter, so keep surfacing them in titles and throughout your content.</p><p>When I asked for sources for my <em>“What is Database Sharding and Partitioning?”</em> query, ChatGPT returned results from PlanetScale, PingCap, Baeldung, and GeeksForGeeks. Meanwhile, Google’s top 5 results for the same query in chronological order was:  PlanetScale, Hazelcast, AWS, GeeksForGeeks, and SingleStore.</p><p>I don’t have all the answers yet, but one thing is clear: if we’re moving away from SEO dependency, we need to rethink how we create content.</p><h2 id="product-led-content-is-what-your-content-marketing-efforts-is-missing"><strong>Product-Led Content is what your content marketing efforts is missing.</strong></h2><p>We’ve established that top-of-funnel informational content—things like “What is serverless computing?”—is driving less traffic to websites. People are finding answers faster elsewhere, whether through AI chatbots, Google’s AI Overview, or directly from communities and forums.</p><p>This shift could actually be a <strong>blessing in disguise</strong> for content marketers. For years, SEO-driven strategies have forced teams to churn out broad, educational content that often had little to do with their product, all in an effort to capture as much traffic as possible. But traffic for its own sake has never been the goal. The real goal is attracting <strong>high-quality leads that convert into customers.</strong> If content doesn’t contribute to revenue through brand trust, affinity, or direct conversions, it’s just noise.</p><p>If AI can generate it, it’s probably not worth writing.</p><p>The kind of content that still works today is the kind of content that AI can’t generate and Google can’t summarize in a snippet. It’s <strong>Product-led content.</strong></p><p>Product-led content is content that <strong>naturally integrates the product</strong> into valuable, educational, or thought-provoking narratives. It’s not about forced mentions or awkward sales pitches. It’s about making the product an organic part of a compelling story.</p><p>Product led content done right has the following capabilities:</p><ul><li><strong>It’s tied to the product.</strong> The topic is closely aligned with a feature or problem your product solves, so mentioning it feels seamless rather than forced. By the time a reader finishes the article, they’ve learned something valuable and seen how the product fits into the solution. Even if they don’t sign up immediately, they leave with a positive impression. <a href="http://Fly.io">Fly.io</a> does this brilliantly—every blog post is an engaging, technical deep dive that subtly integrates their platform without feeling like a pitch.</li><li><strong>It’s value-driven.</strong> The content delivers insights, workflows, or technical knowledge that the audience can apply, whether or not they use the product. Developers, for example, are naturally skeptical of marketing fluff but <strong>love</strong> deep technical content. Show them how you solved a hard problem. Share your mistakes, your trade-offs, and what you learned. Teach them something they can take away, independent of your product. That’s what earns trust.</li><li><strong>It’s behind-the-scenes and personal.</strong> People love to peek behind the curtain. Share how your team tackled a complex problem, the internal debates that happened along the way, and the trade-offs you made. The best way to structure this is with <strong>“How We Built It”</strong> stories that walk through real engineering challenges and decisions. Even announcement blog posts can follow this structure, making them engaging rather than self-promotional.</li><li><strong>It’s collaborative.</strong> The best product-led content doesn’t come from marketing alone. It comes from working closely with engineers, designers, and product teams who actually build and use the product every day. Without this collaboration, marketing risks producing shallow content, while engineering risks building features that never get talked about. A regular content brainstorming session with product and engineering ensures that what gets written is both <strong>technically accurate</strong> and <strong>deeply useful.</strong></li></ul><p>At work, we evaluate our content ideas through the simple grading system below to make sure we’re prioritizing the right kinds of stories:</p><ul><li><strong>0</strong>: There’s no natural way to mention the product without forcing it.</li><li><strong>1</strong>: The product is relevant but not essential to the narrative.</li><li><strong>2</strong>: The product is useful and integrated but not the only solution.</li><li><strong>3</strong>: The entire post <strong>hinges</strong> on the product—it’s central to the story.</li></ul><p>If search-driven traffic is shrinking, the answer isn’t to panic. The answer is to <strong>double down on content that drives real conversations.</strong></p><h2 id="final-thoughts-and-more-pondering">Final thoughts and more pondering</h2><p>Now that I’ve said we should focus on creating content that get people taking, maybe we should all also be thinking of retaining those engagements. How do we keep those conversations happening within our own ecosystem?</p><p>A few things have been on my mind:</p><h3 id="should-we-bring-back-comment-sections-on-blogs">Should we bring back comment sections on blogs?</h3><p>At some point, most companies decided that managing blog comments wasn’t worth it. Spam, moderation, and low engagement led to a gradual shift away from them. But should we rethink that? In the past, comment sections didn’t just encourage discussion—they kept readers coming back.</p><p>People who left comments often returned to check replies, fostering deeper conversations within the company’s platform. Today, those discussions have moved to Hacker News, Reddit, and X. But what if we could reclaim some of that engagement? What if companies focused on building relationships <strong>inside</strong> their own ecosystem instead of relying entirely on external platforms?</p><h3 id="should-companies-create-ai-powered-search-agents-trained-on-their-own-content">Should companies create AI-powered search agents trained on their own content?</h3><p>As AI-driven search habits become more common, it may be time for companies to take control of that experience. Instead of waiting for Perplexity or ChatGPT to surface their content, companies could train AI chatbots on their documentation, blog posts, and knowledge base. Users could query these AI agents for installation guides, troubleshooting steps, or best practices and get direct, authoritative answers from the source. This would not only improve user experience but also align with how people now expect to consume information by getting a single, definitive answer instead of sifting through multiple sources.</p><p><em>I don’t have all the answers, but I’d love to hear your thoughts about everything I’ve written.</em></p>]]></content:encoded></item><item><title><![CDATA[#TCCS 13: What is Internal Developer Advocacy]]></title><description><![CDATA[Dillion Megida, an internal developer advocate, shares insights into the specifics of the role, answering all your questions including challenges.]]></description><link>https://www.everythingtechnicalwriting.com/internal-developer-advocacy/</link><guid isPermaLink="false">Ghost__Post__6787d02e61e3b6001b7d05b7</guid><category><![CDATA[Developer Advocacy]]></category><category><![CDATA[Career Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Wed, 15 Jan 2025 15:14:29 GMT</pubDate><media:content url="https://res-5.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/dillion.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-5.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/dillion.png" alt="#TCCS 13: What is Internal Developer Advocacy"/><p><em><a href="https://www.everythingtechnicalwriting.com/tag/interviews/">The Tech Content Creator Series</a> is a monthly interview series where I chat with industry leaders in various technical communication roles (technical writers, documentation engineers, developer advocates, and what have you) about their careers. It's like chatting with a mentor, over a cup of coffee.</em></p><p>In this episode, I sat down with<a href="https://dillionmegida.com/"> Dillion Megida</a>, an internal developer advocate at Adyen. Currently residing in the Netherlands but originally from Nigeria, Dillion started his career as a freelance content writer before becoming a full-time front-end developer. He later transitioned to developer advocacy, while seeking a role that would allow him to combine coding and content creation. His first position was as an external developer advocate at Stream, where his audience consisted of customers using the company's product. Now at Adyen, he works as an internal developer advocate, focusing on the company's developers as his target audience.</p><p>Earlier this year, while speaking at the Copenhagen Developers Festival, I met some Internal Developer Advocates from <a href="https://capitaloneshopping.com/s/lego.com/coupon">Lego.</a> This was my first real exposure to such a role. So when I got the chance to speak with Dillion, I was excited to finally be getting answers about this position for myself and others.</p><blockquote><em>Psst! I'm writing a book on developer advocacy for individual contributors. It's a distillation of everything I and others—combined with 15 years of experience as a developer advocate ICs—have learned about being an indispensable rock star developer advocate. <a href="https://everythingtechnicalwriting.substack.com/about?ref=everythingtechnicalwriting.com">Sign up for my newsletter</a> to read the first two chapters for free when it drops! :)</em></blockquote><p>In this episode, you’ll find answers to questions like:</p><ul><li>What is internal developer advocacy?</li><li>How is internal developer advocacy different from external developer advocacy?</li><li>How do you demonstrate value in internal developer advocacy?</li><li>How can one become an internal developer advocate or transition to internal developer advocacy?</li></ul><p>Enjoy!</p><h2 id="what-is-internal-developer-advocacy"><strong>What is Internal Developer Advocacy?</strong></h2><p>Dillion hadn’t planned on transitioning to internal developer advocacy. He enjoyed external developer advocacy at Stream, particularly creating content and supporting customers, though he found the marketing aspects less appealing.</p><p>Unfortunately, he was laid off due to the economic crisis. While searching for new developer advocacy jobs, he discovered internal advocacy while job hunting. Intrigued by this unfamiliar variation, he decided to give it a try, driven more by circumstance than choice.</p><p>Since becoming an internal developer advocate, here’s what he’s learned about the role:</p><p>While traditional developer relations is an inside-out form of advocacy, internal developer advocacy is an outside-in approach focused on developer experience. An internal developer advocate is a developer who serves as a resource for other developers. They are the one who understands how all the pieces fit together, is enthusiastic about advocating for other developers, and are willing to help them grasp core concepts.</p><h2 id="internal-developer-advocacy-vs-external-developer-advocacy"><strong>Internal Developer Advocacy vs. External Developer Advocacy?</strong></h2><blockquote><em>“Technical depth requirements depend on the company and role, whether internal or external. In my current role, I'm not expected to produce all the content for our tools - that's the responsibility of those who build them. However, I need a good understanding of how these tools work to keep information up-to-date and well-structured.</em><br><br><em>In my previous external role, I needed deep technical knowledge of our React SDK. Currently, I focus more on structure, visibility, and availability of content rather than creating technical content from scratch. The level of technical depth required varies based on company expectations, regardless of whether the role is internal or external.”</em><br><br>~Dillion Megida</br></br></br></br></blockquote><p>While both internal and external developer advocacy involve the same three elements—community, code, and content—there are several key differences:</p><h3 id="1-audience"><strong>1. Audience</strong></h3><p>For external advocacy, your audience is customers who use your product to build their startups or projects. In internal advocacy, you're working with two types of developers within the company: platform engineers who build internal tools, and product engineers who use those tools to build customer-facing products.</p><p>As an internal developer advocate, Dilion’s audience are the product engineers, and he bridges the gap between them and the platform engineers to ensure their internal tools are as user-friendly as possible.</p><p>Internal developer advocacy might also mean that you have to cater to different flavours of developers with diverse technology stack within your team. For example, Dillion expected to work between just two groups of engineers, but he has found myself working with multiple teams across the company - CI/CD, security, and various other departments. This broader exposure has been interesting, but also more complex than he anticipated.</p><h3 id="2-content"><strong>2. Content</strong></h3><p>Content creation efforts differs between internal and external developer advocacy. External advocacy focuses on articles, case studies, and demos, while internal advocacy requires adapting to your specific internal developers’ needs. This might involve organizing training sessions, improving platform tool documentation, or addressing immediate challenges. You'll also need creative solutions to break down knowledge-sharing silos and make institutional knowledge—information typically known only to long-term employees—more accessible.</p><h3 id="3-metrics-okrs"><strong>3. Metrics &amp; OKRs</strong></h3><p>Measuring success in developer advocacy is generally challenging. In external developer advocacy, metrics like community growth rate, content engagement, feedback implementation rates, event attendance and engagement, DevRel-enabled marketing qualified leads (i.e., how many people enter the sales funnel from DevRel content or activities) are the order of the day. In internal developer advocacy, it's a bit different.</p><p>Internal developer advocacy metrics and OKRs are focused on improving internal developer happiness and satisfaction. For example, Dillion recently worked on a workflow that allowed engineers to document code through comments and markdown files in their repositories, generating documentation that's publicly available. Success was measured by seeing more engineers documenting previously undocumented pages because the process became more convenient.</p><p>While measuring developer happiness is vague, focus is given to specific improvements that contribute to satisfaction. Dillion's team tracks metrics like:</p><ul><li>Reduction in outdated documentation</li><li>Number of teams using new tools or workflows</li><li>Increased documentation coverage</li><li>Engineer feedback and adoption rates</li></ul><p>Sometimes they can't get exact numbers, but they can observe trends and improvements in developer productivity and satisfaction.</p><h3 id="4-documentation"><strong>4. Documentation</strong></h3><p>The key difference in documentation between internal and external developer advocacy lies in context.</p><p>Internal documentation can assume readers already understand company-specific terms and concepts. For example, you wouldn't need to explain technical fundamentals like containerization—something that would be necessary in external documentation.</p><p>While internal documentation can adopt a more casual tone, it still demands clear organization and structure. Even with this informal approach, keeping information accessible and well-organized remains essential.</p><h2 id="peculiarities-and-challenges-associated-with-internal-developer-advocacy"><strong>Peculiarities and Challenges associated with Internal Developer Advocacy</strong></h2><p>I asked Dillion things he has found challenging or interesting about the peculiar role of internal developer advocacy, and this is what he said:</p><h3 id="proving-value-and-impact-in-internal-developer-advocacy-is-tricky"><strong>Proving Value and Impact in Internal Developer Advocacy is Tricky</strong></h3><p>It can be challenging to demonstrate value in internal developer advocacy compared to external roles. In external advocacy, developers must use formal channels like GitHub, forums, and social media to get help, making an advocate's impact clear and measurable. With internal advocacy, however, product developers often skip the internal developer advocate entirely, going straight to platform teams when they need help, through casual conversations over coffee or lunch.</p><p>While this informal dynamic doesn't reduce the internal developer advocate's importance, it does make their impact less visible. To address this challenge, you must gradually build trust and prove your role's value. This means creating structured processes that ensure you're part of key feedback loops and decisions.</p><p>Dillion emphasizes that the goal isn't to control developer interactions, but rather to showcase the unique contributions you as an internal developer advocate can bring to the table—like organizing feedback, facilitating solutions, and improving processes in ways that wouldn't otherwise happen.</p><h3 id="you-just-might-have-to-gain-deep-understanding-of-different-technical-domains"><strong>You just might have to gain deep understanding of different technical domains</strong></h3><p>Since the role of an internal developer advocate is to connect platform teams to product teams, varieties abound. You may find yourself working on projects with multiple teams around the company—from CI/CD, to security, to business enablement teams, and even DevOps—just like Dillion. The good thing is that you'll gain a lot of valuable domain knowledge and deep understanding of various technical domains.</p><p>For instance, working on a project to improve engineer efficiency, Dillion had to learn about GitLab pipelines so thoroughly that he considered creating a YouTube series about it. Similarly, while working on another project, he had the opportunity to become very proficient with regular expressions—something many developers still struggle with.</p><h2 id="so-you-want-to-become-an-internal-developer-advocate"><strong>So you want to become an Internal Developer Advocate?</strong></h2><p>If you’re thinking of transitioning to internal developer advocacy, here’s Dillion’s advice:</p><p>Consider the company and job description. During interviews, pay close attention to what's expected of you. Ask specific questions about:</p><ul><li>Daily responsibilities</li><li>How success is measured</li><li>Career progression opportunities</li><li>The company's definition of advocacy</li></ul><p>You should know that career paths in developer advocacy aren't always clear-cut, like they are in engineering roles. Some people spend years in advocacy before reaching senior levels, while others transition to director of developer relations or return to engineering.</p><p>Consider what your career might look like in 5–7 years. With external advocacy, there's likely to be continued demand as companies need that external communication channel. Internal advocacy might remain more specific to larger, established companies that can support specialized roles. Smaller companies might not need dedicated internal advocates, as team members can communicate directly.</p><p><em>If you want to reach out to Dillion directly, you can find links to all the places he hangs out online on </em><a href="https://dillionmegida.com/"><em>his website</em></a><em>.</em></p><hr><p><em>Psst! I'm writing <strong>a book on developer advocacy for individual contributors</strong>. It's a distillation of everything I and others—with a combined 15 years of experience as developer advocate ICs—have learned about being an indispensable rock star developer advocate. <a href="https://everythingtechnicalwriting.substack.com/about?ref=everythingtechnicalwriting.com">Sign up for my newsletter</a> to read the first two chapters for free when it drops! :)</em></p><hr/></hr>]]></content:encoded></item><item><title><![CDATA[Public Speaking Hacks to Help You Give Engaging Presentations Worldwide]]></title><description><![CDATA[Learn my top public speaking hacks to give engaging presentations worldwide. From structure tips to audience research, this guide has you covered.]]></description><link>https://www.everythingtechnicalwriting.com/public-speaking-hacks-for-engaging-presentations/</link><guid isPermaLink="false">Ghost__Post__6711546107c73d001be51964</guid><category><![CDATA[Career Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Thu, 17 Oct 2024 18:39:02 GMT</pubDate><media:content url="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Gray-Gradient-Process-of-Brand-Building-Carousel-Instagram-Post--1-.jpg" medium="image"/><content:encoded><![CDATA[<img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Gray-Gradient-Process-of-Brand-Building-Carousel-Instagram-Post--1-.jpg" alt="Public Speaking Hacks to Help You Give Engaging Presentations Worldwide"/><p><em>Introducing Linda’s Career Tidbits, a new series where I answer frequent career questions I’m asked. While these pieces may not be strictly focused on technical writing or technical communication careers, they would be generally helpful. If you have any of such questions you’d like to have me answer, reach out.</em></p><p>Before you can give a talk on any stage, you most likely have to pitch your talk and get it accepted into a program first. I’ve written an article on <a href="https://www.google.com/url?q=https://www.google.com/url?q%3Dhttps://www.everythingtechnicalwriting.com/write-a-conference-talk-abstract/%26amp;sa%3DD%26amp;source%3Deditors%26amp;ust%3D1729078488732050%26amp;usg%3DAOvVaw3oln5VhdyTEUZ7cKAqpI-F&amp;sa=D&amp;source=docs&amp;ust=1729078488745639&amp;usg=AOvVaw0iESL6G9_wmjHH5f6yKGcO">how to come up with impressive talk pitches for your ideas</a>. </p><p>Once your talk is accepted, the next step is preparation.  Here are my go-to <strong>public speaking tips</strong> to make your presentation a success:</p><h3 id="follow-a-public-speaking-presentation-structure">Follow a public-speaking presentation structure:</h3><p>A presentation structure helps set audience expectations, keeps you focused, and makes it easier for both you and your audience to remember key points. It also helps you streamline your thoughts during the drafting stage.</p><p>I default to a variety of structures, depending on the kind of presentation I’m giving. My general go-to structure is:</p><ol><li>State the goal or point of the talk.</li><li>Share a relatable story that highlights why this point is important for your audience.</li><li>Present the solution or opportunity or learning.</li><li>Share a relatable story that demonstrates the solution’s/learning value for your audience.</li><li>Recap and offer next steps or a call to action (CTA).</li></ol><p>Other useful structures for when you’re pitching or talking about a solution:</p><ol><li>What is the big problem we’re facing</li><li>What is the pain this problem is causing for you and your audience</li><li>What are some failed solutions that have been applied to fix this problem</li><li>What is your solution and what success have you seen with the solution?</li><li>What are the next steps?</li></ol><h3 id="research-your-audience">Research your audience:</h3><p>Understand their culture, norms, and preferences so you can tailor jokes, references, and examples to that particular audience. For instance, I usually reference a scene from the Jason Statham Bee Keeper movie to explain how social engineering works. This reference has been well received for my talks in the U.S., but recently at a talk in Croatia, the reference wasn’t well understood because the movie hadn’t shown there. I should not have assumed.</p><h3 id="fewer-slides-more-talking">Fewer slides, More Talking:</h3><p>Use visuals as much as possible on your slides, and avoid bulk texts and bullet point after bullet point.</p><h3 id="practice-thoroughly">Practice thoroughly:</h3><p>Rehearse in conditions similar to the actual event—stand, move around, use gestures, and practice in front of friends. If possible, arrive early to practice on the real stage. Record yourself to review and refine your delivery. Improvement comes through repetition, reflection, and feedback.</p><h3 id="avoid-rigid-memorization">Avoid rigid memorization:</h3><p>Memorizing a script can backfire if you lose your place under pressure. Instead, practice sections individually and mix up the order. For example, </p><p>Practice 1: Beginning -&gt; Middle -&gt; End. </p><p>Practice 2: Middle -&gt; Beginning -&gt; End. </p><p>Practice 3: End -&gt; Beginning -&gt; Middle. </p><p>This helps you adapt if needed.</p><h3 id="if-you-lose-your-thoughts-don%E2%80%99t-fret">If you lose your thoughts, don’t fret:</h3><p>If you lose your train of thought, repeat your last point to get back on track or ask the audience a reflective question to buy yourself a moment to regroup.</p><h3 id="engage-your-audience">Engage your audience:</h3><p>Use pauses, questions, and mental exercises to keep them involved.</p><h3 id="warm-up-your-voice">Warm up your voice:</h3><p>Just like warming up a car after it’s been idle, warm up your voice before taking the stage with exercises like tongue twisters.</p><p>For more on the topic of giving engaging presentations, here’s one of my favourite resources on public speaking: <a href="https://www.google.com/url?q=https://www.google.com/url?q%3Dhttps://nofreakingspeaking.com/%26amp;sa%3DD%26amp;source%3Deditors%26amp;ust%3D1729078488735496%26amp;usg%3DAOvVaw12oMI_KvjaRxONOdvovbWN&amp;sa=D&amp;source=docs&amp;ust=1729078488746305&amp;usg=AOvVaw1myjSbKrJuVEoDoe173MTy">NoFreakingSpeaking</a></p><p>P.S. I'm writing a book for Developer Relations Individual Contributors that will feature more communication tips like this. Subscribe to the newsletter below to stay up to date and be the first to know when it is published, as well as to be eligible for a free copy.</p>]]></content:encoded></item><item><title><![CDATA[Am I Still a Junior Professional?]]></title><description><![CDATA[Find out if you're no longer a junior professional.]]></description><link>https://www.everythingtechnicalwriting.com/am-i-still-a-junior/</link><guid isPermaLink="false">Ghost__Post__67114f6d07c73d001be51953</guid><category><![CDATA[Career Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Thu, 17 Oct 2024 18:11:42 GMT</pubDate><media:content url="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Blue-and-Red-Inspirational-Self-Love-Steps-Instagram-Post--1-.jpg" medium="image"/><content:encoded><![CDATA[<img src="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Blue-and-Red-Inspirational-Self-Love-Steps-Instagram-Post--1-.jpg" alt="Am I Still a Junior Professional?"/><p><em>Introducing Linda’s Career Tidbits, a new series where I answer frequent career questions I’m asked. While these pieces may not be strictly focused on technical writing or technical communication careers, they would be generally helpful. If you have any of such questions you’d like to have me answer, reach out.</em></p><p>I sometimes have the privilege of mentoring newbie professionals, and one question I’m often asked is, “At what point do I stop identifying as a junior professional?”. Here’s my answer to that:</p><p>If you’re employed, your organisation likely has a level matrix you can use to assess yourself.</p><p>It’s important to remember that moving up a level isn’t about how long you’ve been in a role but rather about your growth in skills and abilities. You could stay in a position for 4 years and still be considered junior if your skills haven’t advanced. It’s really about your confidence in your abilities, the complexity of the projects you take on, and how well you navigate your field independently.</p><p>However, if your company doesn’t have a level matrix, or you’re not currently employed, here’s a general guide to help you determine if you’ve moved beyond the junior stage:</p><!--kg-card-begin: html--><table>
<thead>
<tr>
<th>Metric</th>
<th>Junior</th>
<th>Mid-Level</th>
<th>Senior</th>
</tr>
</thead>
<tbody>
<tr>
<td>Skill Mastery</td>
<td>Developing foundational skills, often focused on learning and understanding core concepts.</td>
<td>Proficient in most core concepts, comfortable with complex concepts, and able to apply them in practice.</td>
<td>Expert in a broad range of skills, with deep specialization in some areas, and can learn new skills quickly.</td>
</tr>
<tr>
<td>Scope of Projects</td>
<td>Works on smaller, well-defined tasks or projects with a narrow scope.</td>
<td>Manages moderately complex projects with broader scope, able to connect different aspects of a project.</td>
<td>Leads large, complex projects that have a significant impact, considers long-term implications.</td>
</tr>
<tr>
<td>Autonomy in Problem-Solving</td>
<td>Relies heavily on guidance and needs detailed instructions.</td>
<td>Can solve most problems independently but seeks help for unfamiliar challenges.Takes ownership of projects and can lead small initiatives or sub-teams.</td>
<td>Solves complex problems creatively and independently, often consulted for solutions to tough challenges.Leads large projects, influences strategic decisions, and is often a key decision-maker or advisor.</td>
</tr>
<tr>
<td>Understanding Best Practices</td>
<td>Learning and applying best practices with guidance, and may not yet recognize why they matter.</td>
<td>Understands best practices and why they matter, and applies them consistently, plus recognises when to adapt them.</td>
<td>Defines and sets best practices, understands trade-offs, and knows when to deviate based on context.</td>
</tr>
<tr>
<td>Contribution to Team</td>
<td>Primarily focused on their own tasks, and have limited contribution to broader team success.</td>
<td>Contributes to team discussions, occasionally assists peers, and shares insights.</td>
<td>Actively mentors others, drives team initiatives, and plays a key role in fostering team growth.</td>
</tr>
<tr>
<td>Mentoring</td>
<td>Rarely mentors others, as they are still focused on their own learning.</td>
<td>Provides guidance to junior colleagues, helps with peer reviews, and shares knowledge.</td>
<td>Regularly mentors juniors and mid-level professionals, creates learning opportunities, and provides career guidance.</td>
</tr>
<tr>
<td>Collaboration</td>
<td>Collaborates mainly within their immediate team, with limited cross-functional interaction.</td>
<td>Works well in cross-functional teams, understands how their work fits into larger goals.</td>
<td>Facilitates cross-team collaboration, builds bridges between departments, and aligns team efforts with strategic goals.</td>
</tr>
<tr>
<td>Communication</td>
<td>Reports on progress, may struggle with articulating complex concepts clearly.</td>
<td>Communicates effectively with both technical and non-technical stakeholders, can convey ideas and feedback.</td>
<td>Excellent communicator, adapts messaging to diverse audiences, and often represents the team or company externally.</td>
</tr>
<tr>
</tr>
</tbody>
</table><!--kg-card-end: html-->]]></content:encoded></item><item><title><![CDATA[#TCCS 12: How to Become a Developer Advocate with Gift Egwuenu]]></title><description><![CDATA[Gift Egwuenu, an award-winning dev advocate and tech content creator answers all the questions you may have on how to become a developer advocate. ]]></description><link>https://www.everythingtechnicalwriting.com/become-a-developer-advocate/</link><guid isPermaLink="false">Ghost__Post__66eb4ab9d0b66e001b863716</guid><category><![CDATA[Interviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Thu, 26 Sep 2024 04:55:12 GMT</pubDate><media:content url="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/gift.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/gift.png" alt="#TCCS 12: How to Become a Developer Advocate with Gift Egwuenu"/><p><em><em><a href="https://www.everythingtechnicalwriting.com/tag/interviews/">The Tech Content Creator Series</a> is a monthly interview series where I chat with </em>industry leaders <em>in various technical co</em>mmunication<em> roles (technical writers, documentation engineers, developer advocates, and what have you) about their careers.</em> It's like chatting over a cup of coffee with a mentor. </em></p><p>On this episode, I sat down with Gift Egwuenu, who is a celebrated public speaker and tech content creator. She answered all the questions I've been asked about on how to become a developer advocate. In this episode, you'll find answers to questions like: </p><ul><li>What skills do you need to become a developer advocate?</li><li>How can you start acquiring the skills necessary to become a developer advocate, and what resources can I explore as guides? </li><li>Is Devrel different from technical content marketing?</li><li>How can you create a developer advocacy portfolio?</li><li>How much coding knowledge do you need to pivot to developer advocacy? </li></ul><p>Enjoy!</p><p><em><strong>Me: Can you tell me about yourself?</strong></em></p><p><strong>Gift</strong>: I'm Gift Egwuenu, a developer advocate at Cloudflare with seven years of experience in the web/tech industry. I began my career as a content developer before transitioning to developer advocacy. My passion lies in teaching and sharing knowledge, which are some key reasons why I enjoy my current role.</p><p><em><strong>Me: How did you learn about developer advocacy as a career option? You've already told us it's not your first foray into tech. Was there a specific experience or project that sparked your interest in this field?</strong></em></p><p><strong>Gift</strong>: I knew about developer advocacy early in my tech career through friends in the role, but I wasn't initially interested. I wanted to focus on front-end engineering for at least five years and was only 2 years into my career at the time. Surprisingly, I found myself doing advocacy work in my free time - blogging, making YouTube videos, and speaking at conferences. It was just a hobby until someone assumed it was my actual job. That's when I realized all this fun stuff could be a real career path, and I started considering developer advocacy seriously.</p><p><em><strong>Me: From what you've shared so far, your foray into developer advocacy was unintentional, but something made you stay. What would you say was the one thing that made you decide it was the career path for you?</strong></em></p><p><strong>Gift</strong>: What kept me in developer advocacy was my passion for sharing knowledge. Regardless of whether it was my full-time job, I was happy to keep doing it. Despite opportunities coming my way, I initially stuck to my goal of reaching the senior developer level because mentally, I wasn't ready for that switch. I wrote articles, hosted events, and conducted workshops in my free time, which my employer supported even though they weren't part of my job description. Even when I had a role combining front-end engineering and community management, I preferred doing advocacy work independently in my free time. The flexibility to pursue these interests alongside my job was perfect for me at that stage in my career.</p><p><em><strong>Me: You've given me a little foray into developer advocacy. From my understanding, it involves a blend of both technical and soft skills. What would you say are the most crucial skills for success in this role?</strong></em></p><p><strong>Gift</strong>: The role of a developer advocate is multifaceted, blending technical and soft skills. Technical expertise is crucial for speaking developers' language and understanding their challenges. My five years as a developer helped me understand their struggles and offer useful solutions. I’d say having developer experience is a big plus for effective communication, even for less technical DevRel roles. Soft skills, especially public speaking, are equally important. While language preferences vary by company, flexibility is key. For instance, I mainly use JavaScript and TypeScript, but I've had to learn Python too.  You're taking your tech skills and adding a whole new layer on top. It's all about adapting to solve problems with whatever tech is needed.</p><p><em><strong>Me: From your explanation, there seems to be a lot of marketing going on in the role. What would you say is the one thing that differentiates developer advocacy from technical content marketing? Are there any emerging or current trends in the field?</strong></em></p><p><strong>Gift</strong>: Developer advocacy falls under the broader umbrella of developer relations, which includes various roles. While there's some overlap with technical content marketing, the key difference is our approach. We're not selling; we're solving problems for developers. If someone's struggling to use our product to build something, we focus on helping them figure it out, not just telling them how great our product is. Current trends include more community-driven and video content, AI in documentation, measuring impact, and expanding into new tech areas like blockchain and IoT. Ultimately, what sets developer advocacy apart is our focus on helping developers, not selling to them.</p><p><em><strong>Me: What was your first role like as a developer advocate? Were there any surprising responsibilities?</strong></em></p><p><strong>Gift</strong>: I've been in just one developer advocacy job, which is my current job at Cloudflare. In my three years in this role, I've learned a lot. While conferences and video-making were familiar, content strategy surprised me. It's not just about cool ideas; you need to consider audience needs and company benefits. SEO for YouTube was new too. The biggest shock was the multitasking – you're constantly juggling travel, meetings, writing, and problem-solving. The constant context-switching demands excellent time management skills. It's not a job where you do the same thing every day. There are lots of layers to developer advocacy, like in this image: </p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/PHOTO-2024-08-24-09-25-33.jpg" class="kg-image" alt="#TCCS 12: How to Become a Developer Advocate with Gift Egwuenu" loading="lazy" width="635" height="727"><figcaption><em>The sides of developer advocacy that spectators don't see</em></figcaption></img></figure><p><em><strong>Me: How did you land your job at Cloudflare? What was the interview process like, and what should aspiring developer advocates have when applying for their first role?</strong></em></p><p><strong>Gift</strong>: I landed my Cloudflare job unexpectedly. After posting a video review of their product, the director reached out about a developer advocate role. I initially declined it because I wasn’t ready to switch roles and referred a friend who got the job. A year later, they reached out again and I reconsidered. The interview process was intense, involving multiple rounds and a take-home assessment. Since I'd never had this exact job before, I focused on showing how my experience fit the role. I spent a lot of time showing off my work - videos, tech talks, that kind of thing. My tip for aspiring advocates: have work to show, even if it's not company-related. Speaking engagements, videos, or tech articles demonstrate your skills and passion. The key is proving you can do the job, even without the official title.</p><p><em><strong>Me:  How can someone create a great DevRel portfolio? How much does it help in job hunting?</strong></em></p><p><strong>Gift</strong>: Building a killer DevRel portfolio is all about being genuine and starting early. Create content because you love it, not just for job hunting. Start a tech blog, make YouTube tutorials, speak at meetups, contribute to open-source projects, or write for tech publications. Your portfolio shows employers you're already doing the work, even without the title. It demonstrates your communication skills, tech knowledge, and community engagement. Remember, quality beats quantity. Focus on creating valuable content, not just pumping out stuff. I started with Vue courses, which led to opportunities like teaching on LinkedIn Learning. The key is to start now, create what you care about, and keep at it. Show you're not just interested in the job - you're living it!</p><p><em><strong>Me: Can you paint a picture of your typical workday as a developer advocate?</strong></em></p><p><strong>Gift</strong>: The coolest thing about this job is that no two days are the same! On travel days, I'm up early for the airport, prepping for talks, manning our booth at events, giving presentations, and networking. When working from home, I block off time for specific tasks, creating content, attending team meetings, and helping solve developer issues. The only constant is our weekly team meeting with my manager and colleagues. Otherwise, I might be at home one day and on the road the next. It's this variety that makes the job so exciting! You never know what each day will bring, but you're always helping developers and sharing knowledge. That's what makes this job so exciting - the variety keeps you on your toes!</p><p><em><strong>Me: What are the biggest obstacles you've faced as a Developer Advocate? How have you overcome them, and how have they helped you grow professionally?</strong></em></p><p><strong>Gift</strong>: Like any other job, developer advocacy has its challenges. The unclear career progression in this new field was one; it's a relatively new field, and not every company has a clear career ladder. I solved this by openly discussing with my manager, learning to advocate for myself, and planning better. Staying productive while traveling was another; I improved my scheduling and prioritizing skills to tackle this. These challenges have helped me grow, enhancing my communication, planning, and adaptability. They've made me a more well-rounded professional, equipping me with skills valuable in any career.</p><p><em><strong>Me: On the flip side, what would you say you find most rewarding about your role? Any particularly satisfying moments or achievements?</strong></em></p><p><strong>Gift</strong>: There have been several rewarding aspects and moments in my role as a developer advocate. It's awesome when someone tells me they found my content helpful, like last week when I met someone learning from a video I made a year ago. Quick wins are super satisfying too, like when I fixed someone's Cloudflare issue in just 10 minutes. And there are those surprising moments, like when I gave a talk and the room was so full people were sitting on the floor! That was a real “wow” moment for me.</p><p>But the best part is the connections with people. When someone reaches out to say thanks or shares how I helped them solve a problem, that's when I feel I'm making a difference in developers’ lives. It's what keeps me excited about this job every day.</p><p><em><strong>Me: How can someone tell if being a Developer Advocate isn't the right fit for them? Are there signs that might indicate they'd be better suited to a different role?</strong></em></p><p><strong>Gift</strong>: Developer advocacy isn't for everyone. If you're uncomfortable in the spotlight, feel drained after public speaking, or struggle with multitasking, this role might not be your thing. It may not be your cup of tea if you prefer deep tech dives over explanations, or find keeping up with tech trends a chore. Developer advocacy is very public-facing and requires constant adaptation. But don't worry if it doesn't feel right - there are related roles that might suit you better. For instance, a Developer Educator focuses more on content creation with less travel, while a Developer Relations Engineer improves user experience with less public-facing work. The key is to be honest about what you enjoy and what drains you. It's all about finding the right fit for your skills and personality.</p><p><em><strong>Me: What's the most important lesson you've learned as a Developer Advocate that you wish you knew from the start?</strong></em></p><p><strong>Gift</strong>: Initially, I worried about losing my engineering skills as a Developer Advocate. But I've learned that constant upskilling is crucial. You're not coding daily, but you must keep up with tech trends like AI, and understand them to talk about them effectively. My motto is “Always be learning.” It's challenging, but I focus on what each task needs. I now set aside time for learning, even when busy. It's about understanding and explaining complex stuff better. Embrace learning - it keeps you sharp in this ever-changing field.</p><p><em><strong>Me: How important is building a personal brand or strong online presence for a Developer Advocate?</strong></em></p><p><strong>Gift</strong>: A strong online presence is helpful, but not essential for developer advocates. It's great for getting discovered, showcasing work, and promoting events. But personal branding isn't about follower count; it's about providing value. You could be helping newbies or be the go-to for a specific framework. What truly matters is the quality of your work and your impact on the developer community. While a personal brand can help you get noticed, focus on doing great work and helping others. That's what makes you stand out.</p><p><em><strong>Me: What steps should I take to start a career as a Developer Advocate? Are there any resources or communities you'd recommend?</strong></em></p><p><strong>Gift</strong>: To start as a Developer Advocate, you must first understand the role fully. Build a portfolio by writing tech articles on sites like <a href="https://hashnode.com/">Hashnode</a> or <a href="http://dev.to">Dev.to</a>. Make videos, speak at meetups, and contribute to open-source projects to hone both tech and soft skills. Follow and learn from current advocates, and don't hesitate to reach out for advice. Join DevRel communities like <a href="https://devrelcollective.fun/">DevRel Collective</a>, <a href="https://www.devrelx.com/">DevRelX</a>, or  <a href="https://devrelcomafrica.xyz/">DevRel Community Africa</a>. The key is to start doing the work before you have the title. Show you can create content, engage with the community, and explain tech well. Keep at it, and opportunities will come.</p><p><em><strong>Me: What's your top advice for someone who wants to become an aspiring Developer Advocate?</strong></em></p><p><strong>Gift</strong>: The key is to consistently showcase your work. Don't wait for job openings; start demonstrating your value now. Share your projects, help in developer communities, and be active on social media. I know someone who got a job just by being super helpful in a community’s Slack group!</p><p>It's not just about tech skills; you must love teaching and helping others. Start small, be consistent, and build up gradually. It's a marathon, not a sprint. Keep putting yourself out there because you genuinely enjoy sharing knowledge. That passion will make you stand out in this field and the opportunities will come. I greatly recommend you read a book called “Show Your Work” by Austin Kleon</p><hr><h3 id="before-you-go">Before you go: </h3><ul><li>If you'd like to connect with Gift, check out her <a href="https://nl.linkedin.com/in/egwuenugift">LinkedIn</a> and <a href="https://x.com/lauragift_?lang=en">X</a>. And <em>If you enjoyed this piece, share it with a colleague or someone you know will benefit from it. Sharing is caring :)</em></li><li>Subscribe to the newsletter using the form below to be the first to know when a new interview drops. </li><li>I'm writing a a tell-book for developer advocacy titled The Developer Advocacy Blueprint. It's a guide for individual contributors to learn the skills they need to become a developer advocate and get hired. So, if you're an aspiring developer advocate, keep an eye out for it by subscribing to the newsletter below. <a href="https://linda-ikechukwu.ck.page/833abdb9e4"><em>See the landing page for the book here. </em></a></li></ul></hr>]]></content:encoded></item><item><title><![CDATA[#TCCS 11: The Unseen Advantage of UX Education for Technical Writers]]></title><description><![CDATA[Discover Corry Root's journey from intern to Senior Technical Writer at MongoDB, and the pivotal role of UX in her career]]></description><link>https://www.everythingtechnicalwriting.com/ux-for-technical-writers/</link><guid isPermaLink="false">Ghost__Post__65bd48f236f71f001b597b64</guid><category><![CDATA[Interviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Fri, 02 Feb 2024 21:16:02 GMT</pubDate><media:content url="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/maybe.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/maybe.png" alt="#TCCS 11: The Unseen Advantage of UX Education for Technical Writers"/><p/><p><em><em><a href="https://www.everythingtechnicalwriting.com/tag/interviews/">The Tech Content Creator Series</a> is a monthly interview series where I chat with </em>industry leaders <em>in various technical content creation roles (technical writers, documentation engineers, developer advocates, and what have you) about their careers.</em> It's like chatting over a cup of coffee with a mentor. </em></p><p><em>“…When I started in technical writing, I strictly followed best practices and prescriptive grammar rules because everyone else did. However, gaining experience in user experience design taught me the reasons behind these practices and their benefits to users. This not only deepened my understanding, but also sparked my passion for these principles. It also led me to question some of the best practices that were without base that I had previously blindly followed.”</em></p><p>From Intern to Associate, Principal, Manager, and now Senior Technical Writer at <a href="https://www.mongodb.com/">MongoDB</a>, <a href="https://www.linkedin.com/in/corry-root-34460915/">Corry Root</a> has climbed through all possible career levels and emerged victorious.</p><p>On a random Friday afternoon in January 2024, Corry and I got to chat about her impressive career and the lessons she's learned while scaling through levels. We discussed a range of topics, including mentorship, transitioning into management, AI and other emerging trends in technical communication, and the use of self-directed learning as a tool for success.</p><p>This article summarizes the key insights gained from our conversation.</p><h2 id="corrys-career-journey-into-technical-writing">Corry's Career Journey into Technical Writing </h2><p>One thing I find fascinating is uncovering how people came to settle on their career choices. It’s such an intriguing discovery for me because as a high schooler and even up to my college days, I never knew what career I wanted to venture into. My career seems to have found me rather than the other way around.</p><p>By asking people how they came about their career choice, I hope to uncover patterns that might guide others in discovering their strengths and potential careers too.</p><p>From high school, Corry knew she wanted to write, but wasn't sure which genre to focus on. So, she decided to major in English for her undergraduate studies. The major covered various writing styles, including creative writing, nonfiction, and technical communication. It was here that she discovered her affinity for technical writing.</p><p>While exploring these specialization, she discovered her interest in the technical writing track. As she stated, "I love writing. I love being creative. But I also am very logical and gravitate towards technology.”</p><p>To further test out if technical writing was really the career for her, in her junior year of college, she got an internship with a company called <a href="https://www.oracle.com/corporate/pressrelease/oracle-buys-phase-forward-041610.html">Phase Forward (now acquired by Oracle)</a>, a company building clinical trial software, where she helped out with writing documentation. She ended up loving it, and went back for her senior year with a hard conviction that technical writing was exactly what she wanted.</p><p>After her senior year, Phase Forward made Corry an offer to join them. She accepted, and as they say, the rest is history.</p><p><em>Some key learnings from Corry’s career discovery process:</em></p><ul><li>Consider experimenting with available internships or volunteer opportunities to explore a specific career paths you may be curious about. No knowledge is ever wasted and you get to find out what you like and don’t like.</li></ul><h2 id="the-role-of-user-experience-education-in-technical-writing">The Role of User Experience Education in Technical Writing</h2><p><em>Understanding UX design principles aids technical communicators in creating user-centered documentation, which ensures that the people who use (or should use) what you write, can find what they need, understand what they find, and use what they find to meet their needs.</em></p><p>After several years at Phase Forward, Corry began to reconsider her future in technical writing. She was developing an interest in usability testing and user experience design and was contemplating shifting her focus in that direction.</p><p>Fortunately, Phase Forward offered tuition reimbursement, so she enrolled in a Master's program in Human Factors and Information Design at Bentley University. She pursued her Master's degree for three years while working full time.</p><p>Eventually, she realized that although she appreciated and gained much from her masters, she truly enjoyed writing and was not as interested in transitioning to UX design. Nevertheless, she believes that this foundation allowed her to view technical writing in a new light.</p><p>I asked her if her user experience knowledge gave her an edge as a technical writer, and she readily confirmed saying:</p><p><em>“Absolutely. It set me apart. When I started in technical writing, I strictly followed best practices and prescriptive grammar rules because everyone else did. However, gaining experience in user experience design taught me the reasons behind these practices and their benefits to users. This not only deepened my understanding, but also sparked my passion for these principles. It also led me to question some of the best practices that were without base that I had previously blindly followed.”</em></p><p>In my opinion, user experience and psychology principles are essential for any technical communicator interested in creating accessible and effective content. Psychology is being incorporated across various technology fields to optimize results. Marketers use psychological techniques, like the scarcity principle, to entice potential customers to click links, sign up for trials, and become paying customers. UX designers apply principles such as the principle of least effort to design appealing user experiences that prompt desired actions. So, why aren't more technical writers doing the same?</p><p>User experience knowledge helps technical communicators start writing user centred documentation and content for people as they truly are, not as we wish they were or as we think they are. The difference is always visible and would give you an edge.</p><p>If you’d like to dip your feet into some UX content perfect for technical writers, here’s some places to start:</p><ul><li><a href="https://www.usability.gov/how-to-and-tools/methods/writing-for-the-web.html">Usability of writing for the web</a></li><li><a href="https://www.nngroup.com/topic/writing-web/">NNGroup writing for the web</a></li></ul><p><em>Some key learnings from Corry’s stint into user experience design:</em></p><ul><li>Never get too comfortable with what you know. <em>Continual growth and learning is beneficial. Follow your passions, areas of interest, pursue them with the opportunities available to you, and see what doors they open for you.</em></li></ul><h2 id="lessons-on-becoming-a-technical-writing-manager">Lessons on becoming a Technical Writing Manager</h2><p>One impressive thing about Corry’s career trajectory is how she rose from individual contributor to manager and then voluntarily went back to being an individual contributor.</p><p>Management had always been a dream for her. So, when a managerial role became available at CA Technologies, (the company she moved to after Phase Forward got acquired by Oracle, and she could no longer see prospects for career growth there), she immediately applied. Despite feeling uncertain and acknowledging that she had much to learn, she took the leap.</p><p>I asked her what she did to give her an edge over other candidates and she said: “</p><ul><li>First, internal applicants were given priority.</li><li>Secondly, in my interviews, I spoke confidently about my experiences and the management courses I had taken during my master's degree.</li><li>Thirdly, I had also expressed my interest in management to my current manager and mentor, who provided me with numerous tips and advice on improving in my current role to achieve my career goals. I took her advice and made the most of it.</li><li>During the interview, I was asked questions such as: How would you support the team? What areas could the team improve upon? What are some of the challenges the team faces? in an effort to assess my understanding of the group and my ability to be a supportive manager. It helped that I had intimate knowledge of the workings of the group.”</li></ul><p>For Corry, transitioning to management came with a lot of impostor syndrome which is totally normal when entering new terrains and shows that you care. To ensure that you give your best as a manager, Corry recommends seeking lots of feedback. Find out the needs of your team members and understand the expectations from upper management. If there's someone skilled you can learn from, reach out and ask for advice.</p><p>After about 3 years in that managerial role, Corry went back to being an individual contributor because, in her words: “I did a gut check to determine if I was still happy in the role, and I wasn’t. I enjoyed mentoring my peers and helping them succeed. However, I didn't enjoy handling HR matters or layoffs. I also missed writing. As a team manager, you don't get to write as much as when you're an individual contributor. So, I decided to transition back to a principal writing role.”</p><p>K<em>ey learnings from Corry’s stint into management:</em></p><ul><li>Don’t persist in something that is not the right fit. Experiment and stay open to new opportunities, but have the courage to leave when your time is due.</li><li>If you’re looking to get promoted or transition roles, the first place to start is to keep track of opportunities available within your current company. Understand what the expectations are for the next role. Nine times out of ten, that's just talking to your manager and saying, “hey, I would like to be a senior technical writer. What kinds of things do I need to be doing today to be a senior technical writer?”.  Sometimes you're ready for a role somewhere and it's just not available for you at the company or it’s not in the budget, then you know it’s time to start looking at other places.</li></ul><p>If you want to read more about climbing the managerial ladder, read this: <a href="https://www.everythingtechnicalwriting.com/climbing-the-devrel-career-ladder/">Climbing the DevRel career ladder.</a></p><h2 id="finding-career-mentors">Finding Career Mentors</h2><p>All through our chat, Corry stressed the importance of mentorship in overcoming career hurdles. Here are some of the tips she shared for finding mentors and maintaining mentorship relationships:</p><ul><li>Don't hesitate to reach out, ask questions, and seek mentorship both within and outside your organization. Many people have benefited from informal mentorship throughout their careers and are eager to give back. So, just courteously ask questions.</li><li>Your current manager can be a good starting point for finding mentorship. Inform them about the type of guidance you're seeking; they might be able to connect you with someone or provide ideas. For example, when Corry needed design mentorship, she asked her managers if there was a design professional she could connect with. They recommended a suitable contact, which proved beneficial.</li><li>To maintain relationships without becoming burdensome, don't hold on to a mentor indefinitely.</li></ul><h2 id="challenges-in-a-technical-writing-career-and-how-to-overcome">Challenges in a Technical Writing Career and how to Overcome</h2><p>Going from intern to manager to principal technical writer, Corry has seen all but everything, and she’s able to come out on top. She shares some challenges she’s encountered in the course of her career and how she navigated it:</p><ol><li><strong>Feeling stuck in a role?</strong> Stay proactive in interviewing and seeking opportunities outside, and stay informed about potential growth paths.</li><li><strong>Navigating growth in a bigger company?</strong> Faced with the vastness of a larger company, identifying growth opportunities can become a challenge. Actively track available opportunities, understand the company’s landscape, and develop strong relationships with stakeholders.</li><li><strong>Dealing with organizational changes like acquisitions?</strong> Embrace change as inevitable, let go of preconceptions, recognizing that change, though challenging, can bring new opportunities.</li><li><strong>Do not have a technical foundation?</strong> As a technical writer, it’s good to have some technical foundation, so you can respect the time of your engineers and their knowledge by educating yourself enough so that you can communicate effectively with them. To help, embrace self directed learning, where you actively seek out information, educate yourself, and pursue your areas of interest.</li></ol><h2 id="once-a-technical-writer-always-a-technical-writer">Once a technical writer, always a technical writer</h2><p>To round off, I asked Corry what the future holds for her, and if she sees herself in any other profession, to which she replied “I know I love to write, so I don't think I'm going to be moving away from it.”</p><p><em>This blog is a synthesis of all the insights from my chat with <a href="https://www.linkedin.com/in/corry-root-34460915">Corry Root, Senior Technical Writer at Mongo DB</a>, and aims to inspire and educate individuals navigating the fascinating terrain of technical writing. If you enjoyed it, share it with a colleague or fellow technical writer. Sharing is caring :)</em></p>]]></content:encoded></item><item><title><![CDATA[How to Write a Conference Talk Abstract That Will Get Accepted]]></title><description><![CDATA[Over the course of my career as a software engineer, technical writer, and now
developer advocate, I’ve probably given over 30 talks (both online and in
person). As a result, I know a thing or two about writing abstracts and have
gained insights into what it takes to write abstracts with a higher chance of
being accepted.

In this article, I will address the top three questions I frequently receive
about submitting talk abstracts to conferences:

 * What topics should my talk abstract cover?
 * ]]></description><link>https://www.everythingtechnicalwriting.com/write-a-conference-talk-abstract/</link><guid isPermaLink="false">Ghost__Post__6540c6d6d4e646001b68bbf9</guid><category><![CDATA[Career Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Tue, 31 Oct 2023 09:41:01 GMT</pubDate><media:content url="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/abstract23.jpg" medium="image"/><content:encoded><![CDATA[<img src="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/abstract23.jpg" alt="How to Write a Conference Talk Abstract That Will Get Accepted"/><p>Over the course of my career as a software engineer, technical writer, and now developer advocate, I’ve probably given over 30 talks (both online and in person). As a result, I know a thing or two about writing abstracts and have gained insights into what it takes to write abstracts with a higher chance of being accepted.</p><p>In this article, I will address the top three questions I frequently receive about submitting talk abstracts to conferences:</p><ul><li>What topics should my talk abstract cover?</li><li>What should be included in the abstract, and how should I structure it?</li><li>How long should my talk abstract be?</li></ul><h2 id="on-abstract-topic-talk-about-what-you-know">On abstract topic: Talk about what you know</h2><p>Think about your experiences. What have you learned? In what ways have you grown? Are there things you know now that you wish you had known earlier? If you could go back in time three years, what would you tell yourself? That's a good starting point.</p><p>Please focus on discussing topics you are familiar with. Conference abstract reviewers can usually tell when you’re bluffing. Based on my experience, the most successful talks are often those that relate to personal experiences, even technical talks.</p><p>For example, let's say you're giving a talk on ‘Introduction to React’. Any React developer can give a talk on 'introduction to React' or find information about it online. There's nothing particularly exciting about that.</p><p>However, a talk titled "My Tumultuous Introduction to React" covering why you decided to learn React, the challenges you faced while learning, the mental model you used to grasp the basics, the top five things you believe everyone learning React should understand to make their journey easier, and how learning React has benefited your career, is a far more interesting talk.</p><p>In the same vein, anyone can search for information on how to install the Chrome browser, but nobody can share your experience of installing it for the first time or the obstacles you encountered. That's something people cannot find on Google.</p><p>In summary, for each topic, consider how to connect it to your personal experience or opinion. Add some life to it.</p><h2 id="on-abstract-structure-start-with-the-topic-state-the-problem-or-paint-point-tease-a-solution-then-finish-off-with-the-takeaways">On abstract structure: Start with the topic, state the problem or paint point, tease a solution, then finish off with the takeaways</h2><p>Your abstract serves as a promise of what conference attendees will learn from your talk. It is essentially a sales pitch to convince conference organizers that your talk would be a valuable addition to their conference lineup.</p><p>The first thing is to make sure that your talk aligns with the conference theme and prospective audience. Then, for structure, your abstract should address the following four important questions in the specified order:</p><ol><li>What is this talk about?</li><li>Why is this talk an important topic or discussion? What is the identified pain point or challenge associated with this talk?</li><li>What is my suggestion or solution for the identified challenge? What is my unique point of view or opinion on this topic?</li><li>Who is this talk prepared for, and what will they learn from attending? Are there practical, actionable takeaways or results that people can expect to get out of this talk? The whole point of your talk or webinar is to leave the audience smarter.</li></ol><p>Specifying the intended audience in your talk abstract can be helpful when submitting to conferences with a diverse audience and multiple tracks.</p><p>To help you answer the questions above for your conference talk abstract, it may be helpful for you to first develop the talk and write a blog post about what you want to say. Understandably, you might be hesitant to do this because what if your talk is not accepted? My answer is that your effort won’t be wasted, as you can always publish the blog post if the talk doesn't get accepted.</p><p>Here is a talk abstract example of mine that has been accepted at a couple of conferences:</p><blockquote> 💡 <strong><strong>Bring development closer to production with valid HTTPS certificates</strong></strong><br><br>Dev/pod parity is one of the major rules of software engineering. With that in mind, if almost all production web pages now load via HTTPS, why is it that almost no one uses HTTPS in development? Because the traditional process of provisioning certificates to local environments is hard. That sucks because when dev doesn’t match prod, bad things can happen. Join me in this talk to learn how to use step-ca (an open-source Let’s Encrypt equivalent) to easily automate certificate issuance in your development environments with just four commands.</br></br></blockquote><p><strong>Sentence 1 is the Statement/Hook. It communicates what the talk is about with concise language:</strong></p><p>Dev/pod parity is one of the major rule of software engineering</p><p><strong>Sentence 2 states the problem:</strong></p><p>With that in mind, if almost all production web pages now load via HTTPS, why is it that almost no one uses HTTPS in development?</p><p><strong>Sentence 3, 4, and 5 teases a solution and evokes a bit empathy of why the problem exists in the first place:</strong></p><p>Because the traditional process of provisioning certificates to local environments is hard. That sucks because when dev doesn’t match prod, bad things can happen. What if there was a tool built for this?</p><p><strong>The final sentences describe precisely what attendees will learn:</strong></p><p>Join me in this talk to learn how to use step-ca (an open-source Let’s Encrypt equivalent) to easily automate certificate issuance to your development environments with just 4 commands.</p><p><em>P.S: This talk is published as <a href="https://www.freecodecamp.org/news/development-production-parity-with-valid-https-certs/">blog post on FreeCodeCamp</a> if you’d like to take a look.</em></p><h2 id="on-abstract-length-keep-it-short">On abstract length, keep it short</h2><p>When writing an abstract, avoid the temptation to cover every detail. Focus on answering the four essential questions and leave it at that. As a general guideline, if you can't summarize your talk in a minute or two using your abstract, then you may not have a clear understanding of your topic.</p><p>Keep refining your abstract until you can convey it in a minute, aiming for a length of around 100-150 words. Once you're done, seek assistance from someone else to help you edit and assess the clarity of your points. Additionally, create a compelling title that sparks curiosity in readers, enticing them to want to learn more.</p><h1 id="conclusion">Conclusion</h1><p>Unfortunately, even if you follow all the guidelines mentioned above, there is still a possibility of your talk being rejected. The selection of your talk by conference organizers or reviewers depends on a number of factors that are unrelated to the quality of your abstract. </p><p>It could be that a similar talk has already been accepted, or that there are limited speaking slots and other talks were given priority, or perhaps your talk was not completely aligned with the conference theme. Regardless of the reason, don't let rejection discourage you. Keep applying, as it is a numbers game. May the force be with you.</p>]]></content:encoded></item><item><title><![CDATA[DevRel Career Ladder: How to go from Developer Advocate to Head of Developer Advocacy]]></title><description><![CDATA[Right now, my 3-year goal is to go from being a Developer Advocate Individual
Contributor (IC) to head or director of developer
advocacy/relations/marketing/education. For context, I transitioned from
technical writing to developer advocacy roughly a year and 4 months ago.

Adhering to the wisdom of the proverb "make hay while the sun shines,” I decided
that it was wise to start now to gather insights on what was required of me to
achieve such a feat. What better way to gain this insight than by]]></description><link>https://www.everythingtechnicalwriting.com/climbing-the-devrel-career-ladder/</link><guid isPermaLink="false">Ghost__Post__6540ba6ad4e646001b68bbd8</guid><category><![CDATA[Career Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Tue, 31 Oct 2023 08:40:48 GMT</pubDate><media:content url="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/devrel.jpg" medium="image"/><content:encoded><![CDATA[<img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/devrel.jpg" alt="DevRel Career Ladder: How to go from Developer Advocate to Head of Developer Advocacy"/><p>Right now, my 3-year goal is to go from being a Developer Advocate Individual Contributor (IC) to head or director of developer advocacy/relations/marketing/education. For context, I transitioned from technical writing to developer advocacy roughly a year and 4 months ago.</p><p>Adhering to the wisdom of the proverb "make hay while the sun shines,” I decided that it was wise to start now to gather insights on what was required of me to achieve such a feat. What better way to gain this insight than by seeking advice from individuals already holding such positions?</p><p>I reached out to I reached out to <a href="https://twitter.com/hollylawly">Holly Guevara</a>, Director of Developer Education at PlanetScale, and <a href="https://twitter.com/StCyrThoughts">Jason St-Cyr</a>, Director of Developer Relations at Sitecore. To both of them, I asked the question, “How did you get to your current position, and what do I have to do to get there?”</p><p>Here’s what they had to say:</p><h2 id="start-obsessing-over-content-strategy-and-tying-the-value-of-every-piece-of-content-to-business-goals">Start obsessing over content strategy and tying the value of every piece of content to business goals</h2><p>Across companies, the primary role of a developer advocate is to drive awareness and help companies promote their offerings. This is done through various types of content, such as sample code, demo projects, conference talks, documentation, YouTube videos, blog articles, and more, depending on the specific needs of the company or product.</p><p>As a developer advocate in an individual contributor (IC) role, you’re probably just an executioner, executing on assigned tasks. You don't typically generate ideas, drive content strategy, or prioritize what to work on.</p><p>However, as a head of developer advocacy, education, or relations, these are responsibilities that you would typically handle. You would have to move beyond content creation and start thinking about the bigger picture of content strategy. You would need to articulate how every effort and piece of content contributes to the overall marketing funnel. You would also need to analyze content metrics to identify new ideas and areas for improvement and associate business value with content.</p><p>As the Director of Developer Education at PlanetScale, Holly spends her week analyzing data, generating ideas for the content pipeline, managing the content calendar, assigning tasks to team members, coordinating launches and partnerships, and participating in meetings with executives to discuss the company's direction.</p><p>To start to develop strategy skills within your current company, Holly recommends diving into analytics to answer questions such as: Which types of content perform well? What generates marketing-qualified leads (MQLs) and leads to sales?</p><p><em>Fun fact: After reviewing over 20 job listings for Head of Developer Relations or Developer Advocacy positions, one phrase that appeared in every listing was "build strategy".</em></p><p>Before joining PlanetScale, Holly worked at Auth0, where she eventually became the manager of the technical content team. In this role, she started focusing on the bigger picture of content creation and used analytics to determine which content ideas would bring the most value to the company. When a manager position opened up, her boss reached out to her first because she had already been thinking like a lead.</p><p>As Amruta Ranade, Staff Technical Writer at Cockroach Labs, rightly said in <a href="https://www.everythingtechnicalwriting.com/from-staff-technical-writer-to-developer-advocate-read-amruta-ranades-story/">her interview with me</a>, "you have to start doing the job before the job is given to you".</p><h2 id="take-the-initiative-to-think-beyond-your-assigned-tasks-to-own-orchestrate-and-execute-impactful-projects">Take the initiative to think beyond your assigned tasks to own, orchestrate and execute impactful projects</h2><p>Jason shared a story similar to Holly's. He got into management by identifying the gaps that his boss was missing and taking the initiative to fill them. When a manager position became available, his boss advocated for him to be given the role.</p><p>If you're wondering how you can demonstrate capability beyond your tasks, Jason suggests spotting opportunities for improvement and taking action. Consider current industry trends, the company's position in the ecosystem, and what's happening in DevRel. Are there any suggestions or improvements that can make the team better? For example, you could improve the onboarding process, content prioritization and tracking process, or content collaboration process.</p><p>In addition to identifying areas for improvement, you need to be able to sell your ideas to your boss. Do your research and support your ideas with industry examples or the value the company would gain. You should be prepared to answer questions such as: why should this opportunity be prioritized over others? How important is it? Is the value commensurate with the effort required? You also need to align with other teams as needed and foster collaboration.</p><p>Jason also mentioned that, as an aspiring leader, you should not only identify areas for improvement but also learn to drive collaboration not only within your team but also across departments for certain projects to succeed.</p><h2 id="conclusion">Conclusion</h2><p>If you're fortunate enough to work for an established company rather than an early-stage startup, there's likely already a laid-out DevRel career advancement path in place. Ask your boss about this and inform them of your desire.</p><p>However, if you're employed at an early-stage startup with limited structure, it's up to you to proactively seek out opportunities for growth and advocate for yourself. Jason shared <a href="https://slides.jasonstcyr.com/7vVvwn/slides">his framework for leveling up his DevRel team</a>, and there's also a <a href="https://www.marythengvall.com/blog/2020/6/29/the-camunda-developer-relations-career-path">Developer Relations Career Advancement Guide by Mary Thengvall</a> that provides valuable insights into the skills needed for DevRel professional development.</p><p>Still, Jason also suggests that the fastest way to climb the DevRel career ladder and secure senior positions is by transitioning to growing companies, as it may take longer to progress within larger organizations where others are also vying for the same roles. Gain the necessary experience within your current team and consider joining a growing team where your expertise can be leveraged, especially when working alongside newer team members, which can position you as a senior professional.</p>]]></content:encoded></item><item><title><![CDATA[Contributing to Hacktoberfest as a technical writer]]></title><description><![CDATA[Discover projects participating in Hacktoberfest to which you can contribute as a technical writer or non-programmer.]]></description><link>https://www.everythingtechnicalwriting.com/contributing-to-hacktoberfest-as-a-technical-writer/</link><guid isPermaLink="false">Ghost__Post__65231ed428db4a001b1a1776</guid><category><![CDATA[Introductory]]></category><category><![CDATA[Getting Started]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Sun, 08 Oct 2023 21:40:48 GMT</pubDate><media:content url="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/hacktoberfirst.jpg" medium="image"/><content:encoded><![CDATA[<img src="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/hacktoberfirst.jpg" alt="Contributing to Hacktoberfest as a technical writer"/><p>If you’ve been hearing about Hacktoberfest and would like to participate but do not know how to go about it, I got you.</p><p><a href="https://hacktoberfest.com/participation/" rel="noopener noreferrer nofollow">Hacktoberfest</a> is an annual event that encourages open-source enthusiasts worldwide to come together to contribute, collaborate, and learn. This year marks the 10th anniversary of the Hacktoberfest initiative.</p><p>It’s a global initiative supported by companies like GitHub and DigitalOcean, and participants are rewarded with swag (e.g., T-shirts and stickers) for making a certain number of pull requests to open-source projects. Aside from the swags, the first 50,000 participants to have their first pull or merge requests accepted will have a tree planted in their name through Tree Nation, and participants with four pull requests accepted between October 1 and October 31 will receive a unique digital reward.</p><p>In this article, you’ll discover projects participating in Hacktoberfest to which you can contribute as a technical writer or non-programmer.</p><h2 id="why-contribute-to-open-source-as-a-technical-writer">Why contribute to open-source as a technical writer?</h2><p>When you hear ‘contribute to open-source,’ you probably think it’s something only programmers and code-ninjas do because open-source projects are made up of codebases. However, the truth is that everybody can contribute to open-source because projects need more than codebases to be wholesome.</p><p>As a technical writer, you can contribute to open-source projects by:</p><ul><li>Writing documentation or fixing typos in documentation</li><li>Writing blog posts or tutorial</li><li>Collecting and sorting helpful data</li><li>Translating text</li><li>Offering feedback from user experience tests, e.t.c</li></ul><p>Contributing to open source as a technical writer is a great way to build your technical writing portfolio. It shows potential employers that you take the initiative and seek opportunities to learn, grow, and challenge yourself. It also provides you with the opportunity to build community.</p><h2 id="how-to-contribute-to-hacktoberfest-as-a-technical-writer">How to contribute to Hacktoberfest as a technical writer</h2><p>To participate effectively in Hacktoberfirst, here are a couple of things you should know:</p><ol><li><strong>Get familiar with the basics of Git:</strong> If you haven’t already, you should sign up for either a GitLab or GitLab account. You should learn how to perform tasks like fork a repo, pull a repo to your local machine, push changes to a repo, and initiate a pull request. The <a href="https://github.com/firstcontributions/first-contributions" rel="noopener ugc nofollow">FirstContributions</a> tutorial is a great way to learn how to make your first contribution. Hacktoberfest also has some helpful <a href="https://hacktoberfest.com/participation/#:~:text=projects.vercel.app-,SHARPEN%20YOUR%20SKILLS,-SHARPEN%20YOUR%20SKILLS" rel="noopener noreferrer nofollow">resources on its participation page</a> to help you deep dive into how to contribute to repos on GitHub or GitLab effectively.</li><li><strong>Register on the Hacktoberfest website:</strong> You must register on the Hacktoberfest website using your GitLab or GitHub account anytime between <strong>September 26</strong> and <strong>October 31 </strong>for your contribution to count.</li><li><strong>Find projects to contribute to:</strong> Finding projects to contribute to can be the most challenging part of contributing to open source. For Hacktoberfest, you must contribute to only projects participating in the Hacktoberfest challenge for your contribution to count. I’ve done some digging and compiled a list for you:</li></ol><!--kg-card-begin: markdown--><ul>
<li><a href="https://github.com/search?q=label%3Ahacktoberfest+is%3Aissue+is%3Aopen+no%3Aassignee+is%3Adocumentation&amp;type=issues">A list of open Hacktoberfest documentation-related open on GitHub</a></li>
<li><a href="https://up-for-grabs.net/#/filters?labels=&amp;tags=documentation">Projects with open documentation issues on Up-for-grabs</a> . For each project, 		look for issues with the Hacktoberfest and documentation tags.</li>
<li><a href="https://github.com/szabgab/awesome-for-non-programmers">Open source projects that non-programmers can contribute to by Awesome 		non-programmers</a></li>
</ul>
<!--kg-card-end: markdown--><p><br>If you’d rather not contribute to projects you’re not familiar with, you can also 	check to see if your favorite projects or tools are participating in Hacktoberfest. Reach out to the maintainers. Introduce yourself and tell them about your interest in contributing to the project as a technical writer, and inquire if there are specific tasks you can help with. <br><br>Alternatively, you can review documentation from your favorite projects, look out for typos, or how some pages can be improved structurally and made clear, and suggest that to the contributors or make your changes and open a pull request.</br></br></br></p><h2 id="conclusion">Conclusion</h2><p>In conclusion, you can contribute to open source even as a technical writer. Your first contribution will be intimidating, but once you learn the workflow, it’ll get better. </p><p>Below are some resources you may want to check out to learn more about contributing to open source:</p><h2 id="resources">Resources</h2><ul><li><a href="https://www.freecodecamp.org/news/how-anyone-can-participate-in-hacktoberfest/" rel="noopener noreferrer nofollow">How to Participate in Hacktoberfest – Even if You Don't Write Code</a></li><li><a href="https://medium.com/@deeptikorwar/hacktoberfest-a-technical-writers-musings-and-participation-tips-f121daca8e26" rel="noopener noreferrer nofollow">Hacktoberfest: A Technical Writer’s Participation tips</a></li><li><a href="https://javascript.plainenglish.io/how-to-contribute-to-open-source-as-a-technical-writer-bb708245480c" rel="noopener noreferrer nofollow">How to Contribute to Open-Source as a Technical Writer</a></li></ul>]]></content:encoded></item><item><title><![CDATA[How to generate content ideas for technical writing]]></title><description><![CDATA[Are you struggling to figure out what to write about? Don't worry, you're not alone.
In this article, I’ll present you with some questions you should ponder on, to help you generate a constant flow of article ideas. So, let's get started!]]></description><link>https://www.everythingtechnicalwriting.com/how-to-generate-content-ideas-for-technical-writing/</link><guid isPermaLink="false">Ghost__Post__64c7c5cc791718001bfa533a</guid><category><![CDATA[Content Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Mon, 31 Jul 2023 14:40:51 GMT</pubDate><content:encoded><![CDATA[<p>Are you struggling to figure out what to write about? Don't worry, you're not alone.</p><p>For most people who want to get serious with technical writing, figuring out what to write about is their biggest challenge. </p><p>Whether you're writing to impress future employers, give back to the community, build a technical writing portfolio, or establish yourself as a thought leader or expert in your field, coming up with ideas can be a daunting task. </p><p>In this article, I’ll present you with some questions you should ponder on, to help you generate a constant flow of article ideas. So, let's get started!</p><h1 id="questions-to-ask-yourself-to-generate-content-ideas">Questions to ask yourself to generate content ideas</h1><p>Grab a pen and paper, and do this exercise. If you complete it diligently, you should have at least five new content ideas by the end of this article. Ask yourself the following questions:</p><h2 id="who-is-your-target-audience-and-what-do-they-want-to-know">Who is your target audience and what do they want to know?</h2><p>Defining your target audience is crucial when it comes to writing. Knowing who your audience is will give you a clear direction on what topics to write about. It's better to niche down and specialize when defining your audience.</p><p>Are you writing for beginner data analysts who are trying to make sense of the field? Or are you writing for software engineers turned first-time founders/CEOs? For example, this blog targets technical writers or content creators trying to level up their careers.</p><p>Once you've defined your target audience, the next step is to figure out what questions they have and what they want to know. For instance, beginner data analysts might want to know the differences between the data analyst field and data engineering. That's an excellent topic to write about.</p><p>You can discover what your target audience wants to know by checking forums such as Stack Overflow, Quora, or specific communities on Slack. If you're trying to create content for frontend developers, you can search for "frontend developer" in the search box on Stack Overflow or Quora. People's questions around frontend development will appear, and you can sift through them for content ideas.</p><p>Alternatively, you can ask open-ended questions to your target audience on social media. For example, you can ask "For beginner data analysts out here, what are some concepts or topics you struggle with?" Still, try to make sure that whatever you decide to write about is something that you’re knowledgable about or willing to learn about, so you don’t end up creating fluffy content.</p><h2 id="what-are-the-things-you-already-know-or-just-learnt-related-to-your-field-of-focus">What are the things you already know or just learnt related to your field of focus?</h2><p>Have you just learned a new concept? Where did you get stuck? What mental models did you use to break it down and understand it? For example, say you just learned and finally understood how conditional rendering in JavaScript works; that's a perfect thing to write about.</p><p>Did you recently implement a particular feature in a given project after struggling with it for days? Or did you successfully debug a bug, find a solution, or a workaround to a problem? Write that down. It would be a great way to help out others who might be stuck with the same problem in the future. </p><p>Do you have a contrary opinion on how things are done or against a popularly accepted process? These are all ripe content ideas.</p><p>When I used to run a frontend development blog, this was my go-to exercise for generating content ideas. Whenever I figured out a solution to a not-so-common task, I would usually blog about it. For example, things like how to filter an array based on values from another array, or how to merge objects in an array by key.</p><h2 id="what-are-some-things-you%E2%80%99re-planning-to-learn-or-work-on-soon">What are some things you’re planning to learn or work on soon?</h2><p>The quickest way to reinforce a new concept is to write about it. If you have upcoming projects or concepts you will be learning, make a list of them. If you plan to work with an unfamiliar framework, library, or programming language, write about the process. Take note of where you got stuck and how you overcame those roadblocks. Sharing insights about the learning process is valuable.</p><p>If you plan to read a new book related to your field of study, consider doing a blog post summarising the major points and what you learned from the book. Share your opinion on whether others should follow the same route and purchase the book or course.</p><h1 id="but-these-topics-have-already-been-about-written-before">But these topics have already been about written before</h1><p>One common worry that most writers have is whether they should write about a topic that has been written about before. The answer is yes. Yes, write about it in your own unique way. Don't write something generic. Bring your perspective, stories, language, and thought process to the table.</p><p>In his <a href="https://www.everythingtechnicalwriting.com/technical-writing-books/">book on content creation and marketing, "They Ask, You Answer", Marcus Sheridan wrote</a>: "One of the biggest fallacies I've heard come out of the mouth of experts is that if someone has already written about something, then it's a waste of time for someone else to add their own two cents to the conversation, especially if they're not adding anything new to the conversation. For a lack of a better way of putting this, the people who make these statements are ignorant of the history of the world and are completely missing the mark. You see, at this point, most of what we say is a repeat of what someone else has said... For many readers, yours might be the one that touches them."</p><p>Someone else has definitely written an article on how to generate article ideas for technical writing, but my article may be the one that resonates with you the most.<br>Also, don't write off simple ideas, as what you think is common sense may not be common sense for everyone. Focus on quality, not quantity. Create high-quality content that provides value. You don't have to be an expert to be valuable. At the stage you're at, there is someone who needs what you have to offer.</br></p><h1 id="go-create-some-bomb-ass-content">Go create some bomb ass content!</h1><p>If you followed this blog post as an exercise, you should now have at least five different topic ideas. Take those ideas and start writing! If you're struggling with actually writing the articles, check out this post on the <a href="https://www.everythingtechnicalwriting.com/the-technical-writing-process/">technical writing process</a>. It will help you break down the intimidating task of "TECHNICAL WRITING" into distinct steps that you can check off one by one, making it easier to create content in a systematic way.</p><p>You can let me know on twitter if this article was any helpful to you. Toodles!</p>]]></content:encoded></item><item><title><![CDATA[Recap from the Sustain Africa Session on Open Source Documentation.]]></title><description><![CDATA[Recap of a conversation on the sustainability of open-source documentation, discussing strategies that could be adopted to make open-source documentation more sustainable, user-friendly, and useful in assisting users in attaining their goals.]]></description><link>https://www.everythingtechnicalwriting.com/session-on-open-source-documentation/</link><guid isPermaLink="false">Ghost__Post__64a2b6e2815832001b0f9bf8</guid><category><![CDATA[Content Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Mon, 03 Jul 2023 13:06:41 GMT</pubDate><media:content url="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/osca.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/osca.png" alt="Recap from the Sustain Africa Session on Open Source Documentation."/><p>Sustain Africa Summit is a one-day discourse usually staged as a precursor to the heavily renowned yearly Open Source Africa Festival (OSCAFEST), which has been hosted in Lagos since 2021. A group of open-source users, contributors, maintainers, and enthusiasts gather to discuss strategies to further the sustainability of open-source related resources and people.</p><p>This year, I was invited to anchor and facilitate a conversation on the sustainability of open-source documentation. I guided participants to dialogue, learn, and share with one another about strategies that could be adopted to make open-source documentation more sustainable, user-friendly, and useful in assisting users in attaining their goals.</p><p>Our discussions revolved around these three questions:</p><ul><li>What’s the best piece of documentation you’ve come across?</li><li>What made this piece of documentation particularly pleasant, and how can other documentation adopt these features to improve the user experience?</li><li>What is the worst piece of documentation you have come across? What made the experience terrible? What fixes do you think would make it better?</li></ul><h2 id="best-documentation-examples">Best Documentation Examples</h2><p>Participants mentioned projects like <a href="https://docs.djangoproject.com/en/4.2/">Django</a>, mice DB, <a href="https://www.datadoghq.com/">Datadog</a>, <a href="https://posthog.com/docs">PostHog</a>, <a href="https://paystack.com/docs/">Paystack</a>, and <a href="https://stripe.com/docs">Stripe</a>, as some of the best bodies of documentation they’ve encountered.</p><h2 id="characteristics-of-good-technical-documentation">Characteristics of good technical documentation</h2><p>When I asked what made for a good documentation experience, here's a summary of what was mentioned by participants:</p><!--kg-card-begin: markdown--><ul>
<li>
<p>Docs is structured according to learning or knowledge stage.</p>
</li>
<li>
<p>Doc homepage follows a structured format with the following sections:</p>
<ul>
<li>What is this product ( answering the questions ‘What, Why, Where, How’)?</li>
<li>How can this help the reader?</li>
<li>Where to go for each/different tasks/solutions/problems</li>
</ul>
<p>This method provides a clear and concise way of how information is oraganised for the reader. It allows them to quickly understand what the documentation is about and how it can help them. Additionally, it provides clear directions for where to go for different tasks, solutions, and problems. For example, see fleet MDM docs homepage:</p>
</li>
</ul>
<!--kg-card-end: markdown--><figure class="kg-card kg-image-card"><img src="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Screenshot-2023-06-26-at-20.29.06.png" class="kg-image" alt="Recap from the Sustain Africa Session on Open Source Documentation." loading="lazy" width="2962" height="1728"/></figure><ul><li>Content is written in the second-person voice, directly addressing the reader as 'you', creating a more personal connection between the reader and the text.</li><li>Docs features functional search bar to enable easier findability</li><li>Common errors and roadblocks are documented. For example, the Linux installation guide includes solutions for different problems that people may encounter when installing the operating system.</li><li>Product features a thriving community for support</li><li>The documentation features integration code examples that can be modified and tested out right within the documentation,  so one can preview the data/results before and after testing your modifications. The Stripe and Paystack documentation do this quite well.</li></ul><h2 id="characteristics-of-poor-technical-documentation">Characteristics of poor technical documentation</h2><p>When participants were asked what made for a poor documentation experience, they cited:</p><ul><li>Usage of Jargon, thereby making it not beginner friendly. Jargon can be confusing for beginners who are not familiar with a piece of terminology. To make content more accessible to beginners, it's important to avoid jargon whenever possible. And if you must, it's helpful to provide explanations for any technical terms or acronyms that you do use.</li><li>Documentation is poorly structured or convoluted, making it difficult to navigate and find information. You can find out if your docs are facing this dilemma by conducting a friction test with a newbie user or employee.</li><li>Documentation pages are bulky with so much information, overwhelming the reader and making it difficult to know what to focus on.</li><li>Documentation search experience is broken and does not yield valuable results.</li><li>Documentation does not feature real world examples or code usage.</li></ul><h2 id="tips-to-improve-technical-documentation">Tips to improve technical documentation</h2><p>To round up, I asked participants for additional tips on what could be done to make documentation better for them. Two main points were suggested:</p><ul><li>People who build projects should not be the ones to document it, because of the curse of knowledge. Because, it usually results in docs that are not beginner friendly. </li><li>Differentiate what’s temporary (or dynamic) from permanent (static). Temporary are questions that people keep asking (across social or community platforms like discord). Put those in an FAQ, so people can engage and update what works for them. Use the exact questions people ask as headers, as this makes for better SEO.</li></ul><h2 id="poor-documentation-examples">Poor Documentation Examples</h2><p>Participants were also asked to cite some terrible documentation experiences they’ve had. I will not be mentioning any, because I don’t want it to come off as judgemental.</p><h2 id="conclusion">Conclusion</h2><p>I have shared a recap of this discussion with you, my friends who write documentation, in the hopes that you will learn something new and apply some of these tips from real users to create better documentation for your readers. Selah!</p>]]></content:encoded></item><item><title><![CDATA[Navigating Career Transitions]]></title><description><![CDATA[This article is a brushed-up transcript of a talk I gave on February 21, 2023,
at PyCon Namibia. I decided to convert it into a blog post because I am a
generous queen and so more people can benefit from it.

You know who I'm jealous of? It's those who grew up knowing exactly what they
wanted to be. You know, the ones who would confidently declare, "I'm going to be
a doctor, a musician, a dancer, or a fashion designer, etc!", and then actually
went on to do just that. Meanwhile, the rest of us j]]></description><link>https://www.everythingtechnicalwriting.com/career-transition-tips/</link><guid isPermaLink="false">Ghost__Post__64070b0cd439c7001b8a55a0</guid><category><![CDATA[Getting Started]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Tue, 07 Mar 2023 10:18:21 GMT</pubDate><media:content url="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Blue-Fun-Competitive-Analysis-Brainstorm-Presentation.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Blue-Fun-Competitive-Analysis-Brainstorm-Presentation.png" alt="Navigating Career Transitions"/><p><em>This article is a brushed-up transcript of a talk I gave on February 21, 2023, at PyCon Namibia. I decided to convert it into a blog post because I am a generous queen and so more people can benefit from it.</em></p><p>You know who I'm jealous of? It's those who grew up knowing exactly what they wanted to be. You know, the ones who would confidently declare, "I'm going to be a doctor, a musician, a dancer, or a fashion designer, etc!", and then actually went on to do just that. Meanwhile, the rest of us just go with the flow, until we stumble upon something that clicks.</p><p>If you’re like the rest of us and still trying to figure it all out, I’m here to tell you that it’s totally okay! In fact, I'd argue that we're meant to go with the flow because maturing and ageing allow us to learn more about ourselves and the world around us. This knowledge then helps us discover where we'll thrive, what we enjoy, and what's most important to us.</p><p>This article is for you if you're just starting out in tech or thinking about making a switch, and you’re wondering where to start or how to proceed. As a serial transitioner myself, I’ve had my fair share of transitions: from cloud engineer, to frontend engineer, to technical writer, to dev advocacy, so I have quite some transitioning experience. And here’s how what I would advise:</p><h3 id="1-make-peace-with-change">1) Make peace with change</h3><p>So, you’re starting out in tech, and you’re wondering: “how do I even break in? where should I start? What if I start a job and a year into it, I find out that’s not where my strength and passions lie? Or I find out that the monetary return of continuing on that path is not worth it? What do I do? I would have wasted a year at a job that’s not meant for me, and then I’d probably have to stay stuck in it”.</p><p>First off, let's get one thing straight: career changes are not easy. They're scary and nerve-wracking. But guess what? You can do it! It may be a long and tedious process, but you can do it if you put your mind to it and take the necessary steps to prepare. And the truth is, you’ll never be starting from scratch. You’ll be starting over with what you now know and all the experience you’ve gained. As for the question of where to start, I’d say start from anywhere and figure things out as you go. As a popular Instagram reel says, (excuse my French) ‘The more you fuck around, the more you find out’. To find out, you’ve got to experiment, and so it’s okay if plans change.</p><p>Need some inspiration? Check out <a href="https://www.ted.com/talks/chieh_huang_how_to_know_if_it_s_time_to_change_careers?language=en">Chieh Huang's TedX talk</a>. This guy went from being an English teacher to a lawyer to a video game creator to a toilet paper salesman - all in 15 years!</p><h3 id="2-network-with-people-already-occupying-the-roles-you%E2%80%99re-trying-to-transition-into-preferably-people-who-just-transitioned-too">2) Network with people already occupying the roles you’re trying to transition into (preferably people who just transitioned too)</h3><p>Every time I’ve wanted to transition into a new role, one of the first things I do is reach out to people who currently hold the positions I’m hoping to transition into. Thanks to social media (especially Twitter and LinkedIn) you can easily find such people in abundance. Just search the title of the role you’re hoping to transition into (e.g developer advocate) and people with the same titles in their profiles will pop up, and you can start narrowing it down from there.</p><p>Then, ask a lot of questions. A person who asks questions never gets lost. And here are some of the questions you should be asking:</p><ul><li>Are there any specific communities or resources you recommend for people who are interested in learning more about this industry and connecting with professionals in the field?</li><li>What advice do you have for people looking to transition into this field from another industry?</li><li>What are some of the things you know now that you wish you knew when you were starting out in this role or industry?</li><li>What kind of training or education is typically required for entry-level positions in this field?</li><li>How did you land your current role? What challenges did you encounter and what lessons did you learn from your interviewing experience?</li></ul><p>While doing this, remember that most people have busy schedules, and be respectful of their time. One of my icks is when people enter my DMs with just 'hello or hi, I’d like to talk to you' and nothing else. Don’t be that person. When you reach out to these people on social media, state your name, why you’re DMing them, and any questions you have. Be polite and go straight to the point.</p><h3 id="3-come-up-with-a-learning-plan">3) Come up with a learning plan</h3><p>Hopefully, from networking and asking questions, you now know what is required of a newbie in your desired role or industry. It's now time to assess your skill gaps:</p><ul><li>What are the current skills you have that are relevant to the role or industry you’re transitioning to?</li><li>What new skills do you need to learn in order to break into the industry?</li><li>Is there any training or education that would be beneficial to you in making this transition? Do you need to return to school or obtain a certification?</li></ul><p>Another way to figure out what you need to know or learn is to Look at job listings for your desired role and note common requirements. For example, when I wanted to switch from cloud solutions to frontend development, I knew a bit of HTML, CSS, and JavaScript. But I didn’t know any frameworks, and most jobs required junior frontend engineers to be familiar with one. I chose to learn React because it was more popular.</p><p>One common misconception is that you must have everything figured out before making a move. The truth is that you will never have everything figured out, and that is perfectly fine. Making a career change is a process that will involve some trial and error. You don't have to know everything; you just need to know enough to get your foot in the door. Everything else can be learned on the job. There's a popular saying that if you want to succeed, you should limit yourself.</p><p>So, focus on what you need to learn, create a timetable, and set a deadline for yourself. You don't intend to learn forever, so aim to start applying for jobs in six months or a year.</p><h3 id="4-don%E2%80%99t-quit-your-job-just-yet">4) Don’t quit your job just yet</h3><p>Don't quit your current job unless you have benefactors or have saved up just enough runway for 6 months or a year, depending on how long you think the transition will take. I understand that transitioning and learning can be time-consuming and exhausting. However, you will have bills to pay while transitioning, so stay put. Find a way to balance showing up for your current job with learning the skills required for your desired role. One or two hours per day is sufficient.</p><h3 id="5-buildcontribute-to-meaningful-projects">5) Build/contribute to meaningful projects</h3><p><em>“The difference between you and those who seem to be talented at something is practice; a lot of it”.</em></p><p>You need to put whatever you learn to work; build projects. That’s why I advise people to go for learning resources that are assignment or project-based. This is especially important if you're transitioning to a new career with no experience. You can build a stand-out portfolio of work that showcases your abilities to potential employers by contributing to meaningful projects that are modelled after real-world tasks.</p><p>For example, if you're transitioning to frontend engineering, build a website for a non-profit organization. If you're hoping to become a data analyst, analyze real-world data and draw insights from it. When I was trying to transition into technical writing, I contributed some open-source documentation, and did sample revamps of some doc pages, applying style guides to them, and explaining why I made the changes that I made. Those are the types of tasks that technical writers are expected to carry out, so I did something similar to demonstrate my abilities.</p><h3 id="6-be-visible-learn-in-public">6) Be visible: Learn in public</h3><p><em>“Opportunity doesn’t always come to the most qualified, but to the most assumed qualified”</em></p><p>As you embark on transitioning into a new career, talk about it. How will people know to refer or tell you about opportunities that may suit you if they don't know what you do?</p><p>I can tell you a thousand stories about people who got jobs and access to new opportunities simply by learning in public and sharing. Talk about new things you learn. Talk about the challenges you’ve faced and how you overcame them, or if you haven’t overcome them, then ask for solutions.</p><p>Share on social media (Twitter, LinkedIn), share in communities to which you belong, and so on. You never know who might be watching.</p><h3 id="7-applying-for-jobs">7) Applying for jobs</h3><p><em>"Highlight your abilities, not your experience."</em></p><p>When you have learned enough and have built some projects, it's time to let the cat out of the bag. Revamp your resume, focusing on highlighting your abilities, not your experience. How? Explain the strengths you've mastered due to your previous experience and how those strengths can be uniquely applied to your desired role. Look at the expected responsibilities on each opening you're applying to and list out how the abilities you've developed over time can be applied to it.</p><p>You can showcase your uniqueness with a personal statement on your resume that goes something like this:</p><blockquote>Title: Customer Support Personnel with over 3 Years of Experience, Now Looking to Land Their First Frontend Engineering Role.</blockquote><blockquote>As someone who has interacted with customers on a daily basis for over 3 years, I understand their needs, concerns, and pain points. Therefore, I believe that my background in customer support will help me design interfaces that are intuitive, easy to use, and meet the needs of our customers. I am also skilled at taking complex technical concepts and explaining them in simple, easy-to-understand language, which is an important skill for any engineer.</blockquote><blockquote>In addition, my experience in customer support has given me a strong work ethic, a commitment to excellence, and a willingness to go above and beyond to meet the needs of our customers. I am confident that these traits will serve me well in my new role as a frontend engineer.</blockquote><p>Also, remember that it is a numbers game. Apply to as many jobs as you can; but don't apply to too many that you're overwhelmed and don't have the time to tailor your application to each opening.</p><h3 id="conclusion-career-transitions-are-possible">Conclusion: Career transitions are possible</h3><p>It’ll require some work, and some discomfort, but you can do it. And, it's okay to take a break and do something to recharge when you feel overwhelmed. But don't lose sight of the prize.</p><p>I've just tried to summarize the career transitioning tips that have worked for me as a serial transitioner. Your journey may not be the same as another mine, so it’s up to you to own your journey.1</p>]]></content:encoded></item><item><title><![CDATA[#TCCS 10: On seeking actionable documentation feedback]]></title><description><![CDATA[Welcome to 2023!

This is the first Technical Content Creation Series Episode of the year.

The Tech Content Creator Series is a monthly interview series where I chat with
folks in various technical content creation roles (technical writers,
documentation engineers, developer advocates, and what have you) about their
careers. My hope is for their stories will impact, inspire, and motivate you.

This month, my guest was Damilola Oladele [https://twitter.com/activus_d]. As of
the time of this inte]]></description><link>https://www.everythingtechnicalwriting.com/on-seeking-actionable-documentation-feedback/</link><guid isPermaLink="false">Ghost__Post__640610e2a3a508001b35dd17</guid><category><![CDATA[Interviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Mon, 06 Mar 2023 17:04:06 GMT</pubDate><media:content url="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/dami.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/dami.png" alt="#TCCS 10: On seeking actionable documentation feedback"/><p>Welcome to 2023!</p><p>This is the first Technical Content Creation Series Episode of the year.</p><p><em>The Tech Content Creator Series is a monthly interview series where I chat with folks in various technical content creation roles (technical writers, documentation engineers, developer advocates, and what have you) about their careers. My hope is for their stories will impact, inspire, and motivate you.</em></p><p>This month, my guest was <a href="https://twitter.com/activus_d">Damilola Oladele</a>. As of the time of this interview, Damilola is currently an <a href="https://www.outreachy.org/">Outreachy</a> intern at <a href="https://wagtail.org/">Wagtail</a> where he functions in the capacity of a technical writer intern. In this episode, we discuss what it's like to be an outreachy intern. We also talked about how the Wagtail team leverages its open-source community to get actionable documentation feedback to continually improve its documentation.</p><p>Let’s dive in.</p><h3 id="me-hi-damilola-it%E2%80%99s-nice-to-meet-you-so-you%E2%80%99re-currently-an-outreachy-technical-writer-intern-with-wagtail-can-you-tell-me-what%E2%80%99s-that-like">Me: Hi Damilola, it’s nice to meet you. So you’re currently an Outreachy technical writer intern with Wagtail, can you tell me what’s that like?</h3><p><strong>Damilola</strong>: As the name suggests, Wagtail CMS is a content management system built on the Django framework and can be used to manage all the content of a website. Instead of fiddling with a codebase every time you need to modify the content of a website, you can make changes via the interface provided by the CMS.</p><p>Wagtail CMS has two documentation categories: A user guide for the CMS users and non-technical people, and a Developer guide, which is for the developers who set up and customize the CMS to suit the needs of an organization. In my role as a Wagtail Outreachy intern, I'm primarily concerned with improving the user guide documentation.</p><h3 id="me-let%E2%80%99s-talk-about-outreachy-for-a-moment-because-a-lot-of-people-are-always-trying-to-get-into-outreachy-what-was-the-application-process-like-for-you-what-did-you-do-differently-to-get-in">Me: Let’s talk about Outreachy for a moment, because a lot of people are always trying to get into Outreachy. What was the application process like for you? What did you do differently to get in?</h3><p><strong>Damilola</strong>: Outreachy offers underrepresented people paid internships. In the initial application form, you must clearly explain how you are part of a minority or underrepresented group to be considered for the internship. The response you provide is very crucial, and for me, I narrated real experiences of the kind of bias I have encountered.</p><p>After the initial form-based application, shortlisted applicants enter the next phase which is the contribution stage. Shortlisted applicants will receive a list of potential open-source organizations/projects to contribute to based on their chosen track (UI/UX, technical writing, or programming). I applied to the technical writing track and got a list of open-source projects that needed technical writers.</p><p>After receiving the list of potential projects, you’re expected to pick one or more to contribute to. Personally, I’d recommend picking and sticking to one project to avoid diluting your efforts. I picked Wagtail CMS and opted to work on improving the user guide documentation.</p><p>The contribution phase lasts for a stipulated period, after which mentors choose the best-performing contributors (based on several criteria) to become official interns. I was chosen over about 40 other contributors for reasons best known to my mentors. I started out by making daily contributions in the form of grammatical corrections to the docs. After a while, my mentors asked me to move to the next stage. At this stage, I had to analyze the user guide documentation and identify flaws and ways to improve it, then draft a licensing policy, all of which I submitted. We were also required to write essays about our Outreachy experience every week of not more than 500 words. I think doing all these diligently gave me headway.</p><h3 id="me-i-made-a-tweet-asking-about-ways-to-obtain-actionable-documentation-feedback-you-replied-stating-that-wagtail-includes-a-feedback-box-on-each-documentation-page-you-also-stated-that-this-approach-has-yielded-valuable-insights-the-most-recent-of-which-was-a-suggestion-to-rename-a-section-from-browser-issues-to-browser-compatibility-because-the-former-had-a-negative-connotation-can-you-shed-more-light-on-how-this-feedback-box-is-set-up">Me: I made a tweet asking about ways to obtain actionable documentation feedback. You replied, stating that Wagtail includes a feedback box on each documentation page. You also stated that this approach has yielded valuable insights, the most recent of which was a suggestion to rename a section from browser issues to browser compatibility because the former had a negative connotation. Can you shed more light on how this feedback box is set up?</h3><p><strong>Damilola:</strong> The Wagtail user guide documentation is actually managed using Wagtail CMS; yeah we use our own technology. So, the feedback system is set up in such a way that any feedback is fed back into the CMS's admin interface. At the bottom of each documentation page, we have a rating box with two options: Is this page useful or not? If you select not helpful, you will be taken to a form where you can provide more information about why.</p><h3 id="me-how-often-is-feedback-reviewed-and-acted-upon">Me: How often is feedback reviewed and acted upon?</h3><p><strong>Damilola:</strong> Because Wagtail is an open-source organization, it is determined by the availability of our editorial volunteers. These editors are open-source volunteers who respond to feedback as soon as possible. One editor can post a piece of feedback in a Slack channel for others to consider and act on. I imagine that in a startup, tracking and resolving received feedback would be part of the documentation/content/devrel team's weekly routine.</p><h3 id="me-aside-from-the-feedback-box-on-individual-documentation-pages-what-other-methods-does-wagtail-employ-to-obtain-actionable-documentation-feedback">Me: Aside from the feedback box on individual documentation pages, what other methods does Wagtail employ to obtain actionable documentation feedback.</h3><p><strong>Damilola</strong>: One advantage we have is our huge open-source community. Wagtail CMS is the most popular Python-based CMS, so, there’s a constant stream of people making suggestions of what they think can be improved upon and offering to help.</p><p>Another method by which we obtain actionable documentation feedback is through planned user surveys and interviews. Our approach is to start out by sending surveys to our entire open-source community. Then we identify recurring responses or patterns (if any), decide what should be paid attention to, and then reach out to some survey partakers for a possible one-on-one interview.</p><h3 id="me-what-kind-of-questions-are-featured-in-this-survey">Me: What kind of questions are featured in this survey?</h3><p><strong>Damilola</strong>: In my time here, I've helped organize one user research. The primary goal of this research was to find ways to improve the user documentation guide; to learn what our users think of the documentation as a whole, to identify missing features, and to ensure that we are meeting the expectations of the majority of our users.</p><p>Some of the questions that were asked in the survey were:</p><ul><li>How do you use Wagtail CMS: Developer, Editor, Moderator, or Administrator. Seeing as we have different audiences/user categories, we wanted to make sure that we paid attention to only responses from non-technical users.</li><li>How often do you use Wagtail CMS? The essence of this question was to make sure that we’re focused on people who use the CMS regularly and therefore have a deep familiarity with the product.</li><li>How often do you use the docs? Same reason as above.</li></ul><p>After our survey, we found that the people who have the most difficulty getting started with Wagtail CMS were new users. Then we conducted follow-up interviews with some users, asking questions such as:</p><ul><li>What do they think of the documentation as a whole?</li><li>Have you used other CMS's? How does Wagtail CMS compare?</li><li>How easy is it to work with Wagtail CMS when you’re using it side by side with the documentation?</li><li>What features are not well documented?</li></ul><h3 id="me-what-were-some-challenges-you-encountered-while-carrying-out-this-user-research">Me: What were some challenges you encountered while carrying out this user research?</h3><p><strong>Damilola:</strong> Getting people to make out time for an interview can be tricky because people have busy schedules. One way we got a headset was to send out the survey to people within the organization who aren't developers but have a deep familiarity with the product. This helped us refine our questions and have something to start working with. So, you can start with the existing relationships you have, pending when what you want comes along.</p><h3 id="me-final-question-assume-the-person-reading-this-is-a-lone-technical-writer-on-a-team-looking-to-improve-their-overall-documentation-based-on-your-experience-how-would-you-advise-them-to-approach-this-problem">Me: Final question. Assume the person reading this is a lone technical writer on a team looking to improve their overall documentation. Based on your experience, how would you advise them to approach this problem?</h3><p><strong>Damilola:</strong> I’d say start with using the docs yourself. Follow some how-to guides and see how easy it is for you. If it’s not easy for you, chances are it won't be easy for others.</p><p>The second step is to collaborate and develop strong relationships with, developers to discover if there are undocumented features.</p><p>Last but not least, stay in touch with your community, especially if you're an open-source organization. There may be people in your community who may have used your products in ways that even the core engineers had not considered. However, before throwing out questions to the community, ensure that you are not a novice and that you are familiar with the product so that you can ask relevant questions.</p><hr><p>You can reach out to <a href="https://twitter.com/activus_d">Damilola</a> on Twitter, and read about his Outreachy experience <a href="https://activuscode.hashnode.dev/outreachy-internship-wrap-up">here</a>. Bye.</p></hr>]]></content:encoded></item><item><title><![CDATA[Everything Technical Writing 2022 Recap]]></title><description><![CDATA[Wow. DJ play me, "looks like we made it. Look how far we've come …"

As I pen this down, I'm so emotional. I started this blog out of frustration
(I'll explain soon) and a desire to help, but it's morphed into so much more.
And, I couldn't be more grateful.

Let me explain. It all started with a tweet. I posted this tweet
[https://twitter.com/_MsLinda/status/1389893412669820929?s=20&t=-k0-2LSc-BNagTWzVUzsng] 
about how I was writing for some popular tech publications and making some good
side in]]></description><link>https://www.everythingtechnicalwriting.com/everything-technical-writing-2022-recap/</link><guid isPermaLink="false">Ghost__Post__63a5efbe628d98001de515e7</guid><category><![CDATA[Reviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Fri, 23 Dec 2022 18:19:11 GMT</pubDate><media:content url="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Untitled-design.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Untitled-design.png" alt="Everything Technical Writing 2022 Recap"/><p>Wow. DJ play me, "looks like we made it. Look how far we've come …"</p><p>As I pen this down, I'm so emotional. I started this blog out of frustration (I'll explain soon) and a desire to help, but it's morphed into so much more. And, I couldn't be more grateful.</p><p>Let me explain. It all started with a tweet. I posted <a href="https://twitter.com/_MsLinda/status/1389893412669820929?s=20&amp;t=-k0-2LSc-BNagTWzVUzsng">this tweet</a> about how I was writing for some popular tech publications and making some good side income. I like to be transparent and vocal about what brings me success so others can replicate it and find their own success.</p><p>Little did I know that I was shooting myself in the leg. A few days after that tweet and my DM blew up. People wanted to know what technical writing was and how they could get started because nothing motivates people to take action as much as money does. I did my best to provide detailed responses to a number of people, but it became frustrating, time-consuming, and unsustainable after a while. So I had the brilliant idea of writing an article about what technical writing entails and how to get started. This reasoning gave birth to one of the blog's most popular articles to date: Everything You Need to Know About Technical Writing. The plan was that whenever someone asked me the same question, I would simply send them a link to my article and go about my business.</p><p>That strategy worked for a while and allowed me to breathe until people began asking more questions about various aspects of technical writing. At that point, I decided to take this site seriously and even add a newsletter on top for good measure. I made the decision to write an article each month to address the most common question I received for that particular month.</p><p>I just wanted to look back and see how far the blog and newsletter have come, as well as to remind myself that the unpaid work I've been doing is worthwhile so that I can muster the courage to continue.</p><p>So here's how the Everything Technical Writing blog and newsletter performed this 2022 in numbers (Data from Search Console &amp; Google Analytics):</p><ul><li>308K search impressions resulting in 6.6k clicks</li><li>25k page views</li><li>9.7k new users</li><li>Over &gt;1100 newsletter subscribers with an average open rate of 42.6%</li></ul><p>And here's for impact and community love:</p><ul><li>Helped someone going back into employment after 14 years of employment feel more prepared</li><li>Helped someone who was prepping for a content designer interview with Github gain more clarity</li><li>Helped someone get accepted to Freecodecamp as a writer</li><li>And so much more … and guess what? People loooooove this newsletter! Argh! See the image below for some more gushing …</li></ul><figure class="kg-card kg-image-card"><img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Untitled-design.png" class="kg-image" alt="Everything Technical Writing 2022 Recap" loading="lazy" width="1920" height="1080"/></figure><p>PS: If you're reading this, and you're not yet subscribed to the newsletter, you should. Don't you want to see why all these people love it?</p>]]></content:encoded></item><item><title><![CDATA[#TCCS 9: A thing or two about API documentation with Fortune]]></title><description><![CDATA[The Tech Content Creator Series is a monthly interview series where I chat with
folks in various technical content creation roles (technical writers,
documentation engineers, developer advocates, and what have you) about their
careers. I hope their stories will impact, inspire, and motivate you.

For this episode, My guest was Fortune Ikechi, a Developer Relations Engineer
with Storyblok [https://www.storyblok.com/home]. At Storyblok, one of his
primary responsibilities is to document APIs and e]]></description><link>https://www.everythingtechnicalwriting.com/a-thing-or-two-about-api-documentation/</link><guid isPermaLink="false">Ghost__Post__63a17150de860e001de68042</guid><category><![CDATA[Interviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Tue, 20 Dec 2022 08:38:21 GMT</pubDate><media:content url="https://res-4.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/FORTUNE.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-4.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/FORTUNE.png" alt="#TCCS 9: A thing or two about API documentation with Fortune"/><p><em>The Tech Content Creator Series is a monthly interview series where I chat with folks in various technical content creation roles (technical writers, documentation engineers, developer advocates, and what have you) about their careers. I hope their stories will impact, inspire, and motivate you.</em></p><p>For this episode, My guest was Fortune Ikechi, a Developer Relations Engineer with <a href="https://www.storyblok.com/home">Storyblok</a>. At Storyblok, one of his primary responsibilities is to document APIs and ensure developers have all the information they need to effectively use Storyblok's API. This is why I reached out to him to chat about what goes into API documentation, his transition from frontend developer to Developer Relations Engineer, and everything else in between.</p><p>Fortune's story reinforces the importance of consistently putting yourself out there and obsessing over quality delivery. I hope you enjoy it as much as I did putting it together!</p><h3 id="me-hi-so-tell-me-about-yourself">Me: Hi, so tell me about yourself.</h3><p><strong>Fortune:</strong> My name is Fortune. I'm currently a developer relations engineer at Storyblok, primarily involved with the documentation engineering team. Asides from that, I also get to do a lot of demos for clients — mostly enterprise-level customers — and create content on how to use Storyblok.</p><h3 id="me-so-how-did-you-get-into-tech-have-you-always-been-a-documentation-engineer-or-%E2%80%A6">Me: So, how did you get into tech? Have you always been a documentation engineer or …?</h3><p><strong>Fortune</strong>: I got into tech precisely in 2019 while pursuing my biochemistry undergraduate degree. Before then, I had attended a couple of tech meetups like Google Developer Students' Group, and I also had some acquaintances who were in tech. I began learning PHP on my phone and later received assistance to buy a laptop.</p><h3 id="me-what-was-your-first-gig">Me: What was your first gig?</h3><p><strong>Fortune:</strong> So, after learning some PHP, I went on Twitter and tweeted something like, "Hey guys, so I've been learning some PHP, and I'd really like to get my hands dirty. So, if anyone needs a job or an internship — even if it's unpaid — I'd be happy to take it on". Then this guy that was based in London reached out like, "do you know WordPress?". I replied yes. The truth is, at that point, I didn't actually know WordPress, but I'm a fast learner. I spent about 3 or 4 hours that night reading up on WordPress and how to build stuff with it. I found out that WordPress uses PHP underneath, and I was so excited.</p><p>I started working for this guy, and he paid me 25,000 naira per month. It was well worth it because I learned a lot from this guy. I was building various WordPress sites. After a while, he told me he would increase my earnings to 50,000 naira monthly, but I had to learn React. I spent four months learning JavaScript and React, and worked on some React projects.</p><p>After that four months, I decided to quit because I felt I needed more time to structure my learning and go in-depth. I felt I knew a lot of things, but I couldn't call myself a full-stack engineer or a software engineer.</p><h3 id="me-so-how-did-you-get-into-technical-writing">Me: So, how did you get into technical writing?</h3><p><strong>Fortune</strong>: My path to technical writing was very unplanned. It happened in 2020, during covid. I was back home and was crazy depressed because I was broke. I'd already stopped working for the London guy for about six months to devote more time to my studies, and I was yet to find a new gig. I couldn't go back to the London guy to ask for my old gig.</p><p>One morning, around 4 am, I went on medium and just wrote and published <a href="https://kaycodev.medium.com/the-past-i-wish-id-forget-38da18721502">this article about the story of my life</a>: how frustrated I was, what it's been like growing up, how I've been learning tech, and everything in between. By a stroke of luck, after some weeks, someone from Smashing Magazine reached out (via a message on medium). He said he had just read my story and could see that I had the potential to be a good writer and that he would teach me how to write technical articles. But I needed to know React. I told him I already knew React. Then he told me I'd be paid $200 per article; I almost passed out from excitement. That was going to be my first time earning DOLLARZ!!!!!!!!.</p><p>We went back and forth for three weeks before settling on my first article topic: Using MobX as a state manager in React applications. And then it took another back and forth over 4 drafts for my first article to be published in Smashing Magazine! That guy was literally my angel!</p><p>People will always ask me how I got into Smashing Magazine, and I'd always say I didn't even apply. It's funny because before this guy reached out to me, I had applied countless times to Logrocket and a couple of other dev publications and was always rejected. With my article now published in Smashing Magazine, I sent the link to the head of content at Logrocket, and I was accepted as an author on Logrocket within three days.</p><p>And that's how I got started in technical writing. I just kept going from there. So many people would reach out and say, 'Wow! I read your article on Smashing, would you like to write for us?'. That's what I did for the majority of the Covid period. It wasn't until 2021 that I returned to the job market to resume coding.</p><h3 id="me-so-devrel-how-did-that-happen">Me: So, DevRel. How did that happen?</h3><p><strong>Fortune</strong>: After covid, I went back into the job market and got a job as a frontend engineer for a company based in the US. While at that job, I realized I wanted to do more than write code all day. Writing code is fun for me, but I wanted to do more. I wanted to write more about what went into the features I was building.</p><p>I started talking to people I met on Twitter, like <a href="https://twitter.com/iamdillion">Dillion.</a> He was the one who told me about the DevRel niche. We spent 3 months researching the field and how we could get into it. Then we challenged ourselves that before the end of 2021, we were going to get DevRel jobs. From there, every day, we'd apply to over five DevRel jobs with personalized resumes and cover letters. It was exhausting, but we both persisted until we landed our respective DevRel jobs.</p><h3 id="me-so-your-interview-with-storyblok-what-did-you-do-to-stand-out-and-land-the-job-considering-you-had-no-prior-devrel-experience">Me: So, your interview with StoryBlok. What did you do to stand out and land the job, considering you had no prior DevRel experience?</h3><p><strong>Fortune</strong>: I believe it was my knowledge and experience with writing technical articles for well-known platforms such as Smashing Magazine. On one of the calls, I said something like, "oh, I write good articles too. I have some articles published in Smashing Magazine, and here are some links to them." That piqued their interest, and they were impressed because they already had a relationship/partnership with Smashing Magazine. I also mentioned that I had community experience (I used to lead the Google developer student club at my university) and that I had spoken at a few local conferences.</p><p>So, basically, having experience with documentation helped tremendously, and even more was having experience managing communities because when I joined, I was managing the community on Discord, for a couple of months, before I moved on to focusing more on documentation cos that's my core strength.</p><h3 id="me-now-lets-talk-about-api-documentation-you-talk-about-that-a-lot-on-twitter-so-say-someone-wants-to-learn-or-specialize-in-api-documentation-where-should-they-start">Me: Now, let's talk about API Documentation. You talk about that a lot on Twitter. So say someone wants to learn or specialize in API Documentation. Where should they start?</h3><p><strong>Fortune</strong>: First and foremost, you should understand code. I see many people say technical writing is a non-coding field, which is pretty misleading. As an API documentation engineer, you'll probably know more about endpoints and APIs than other people in the company because you'll be like the custodian of the company's API. You can't be an excellent API documentation engineer without a basic understanding of how to write code, how developers use the APIs, and how to test-run multiple APIs.</p><h3 id="me-in-your-journey-as-an-api-documentation-engineer-have-there-been-notable-resources-or-tools-that-have-been-of-help-to-you">Me: In your journey as an API documentation engineer, have there been notable resources or tools that have been of help to you?</h3><p><strong>Fortune</strong>: The <a href="https://idratherbewriting.com/learnapidoc/">API Documentation course from Tom Johnson</a> is definitely one of the (if not the best) resources out there. The <a href="https://shalvah.teachable.com/p/api-documentation-for-developers">API Course by Shalvah</a> is also good. Then there's this book, docs for developers.</p><p>Also, remember that there's no singular format for API documentation. So the format you see in these courses may not be what your company will use, but the fundamentals are still the same.</p><p>Next, learn about your users and the community. The community/users change everything. You cannot write the same API for, let's say, a FinTech community the same way you write for a SaaS community or a community of Kubernetes folks. It's just like totally different, right?</p><p><strong><em>The end.</em></strong></p><p>You can find Fortune on <a href="https://www.dropbox.com/scl/fi/n5r5owq9n1lbxeq4dqwce/TCCS-A-thing-or-two-about-API-documentation-with-Fortune.paper?dl=0&amp;rlkey=0033wq6diq50z3gkb79n3t666">Twitter</a> or <a href="https://www.linkedin.com/in/fortune-ikechi-99199a13b/?originalSubdomain=ng">LinkedIn</a>.</p>]]></content:encoded></item><item><title><![CDATA[Musings from recording and editing my first YouTube video]]></title><description><![CDATA[If you follow me on Twitter, you'll know that I recently transitioned from being
a technical writer to a developer advocate. It's been over 4 months, and I love
it. Admittedly, the context switches due to the contrasting roles associated
with dev advocacy aren't always fun. Still, they're ideal for someone like me
who gets bored easily and can't stay focused on one project for too long.

So, asides from producing written content, I was recently asked to make basic
explanatory YouTube videos for ]]></description><link>https://www.everythingtechnicalwriting.com/makiing-my-first-youtube-video/</link><guid isPermaLink="false">Ghost__Post__635a80af4b9946001db28d7b</guid><category><![CDATA[Content Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Thu, 27 Oct 2022 13:30:13 GMT</pubDate><media:content url="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/youtube.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/youtube.png" alt="Musings from recording and editing my first YouTube video"/><p>If you follow me on Twitter, you'll know that I recently transitioned from being a technical writer to a developer advocate. It's been over 4 months, and I love it. Admittedly, the context switches due to the contrasting roles associated with dev advocacy aren't always fun. Still, they're ideal for someone like me who gets bored easily and can't stay focused on one project for too long.</p><p>So, asides from producing written content, I was recently asked to make basic explanatory YouTube videos for our open-source tools. In all, it was a wholesome learning experience, and the feedback I got was that I didn't do so badly for my first video, given the little time I had.</p><p>In this article, I just thought I'd share my process and what it took for me to record and edit my first explanatory YouTube videos for anyone interested. So yes, this is an article on how not to suck at your first' make a YouTube video assignment'.</p><h2 id="step-1-choose-your-battle-weapon-tool">Step 1: Choose your <s>battle weapon</s> tool</h2><p>First things first, I had never edited a video before, so I most certainly did not know what the go-to tools were. I spoke to a couple of my mutuals who had published a couple of youtube videos and asked them for recommendations. The top three tools that were mentioned were:</p><ul><li><a href="https://www.blackmagicdesign.com/products/davinciresolve">Davinci Resolve</a></li><li><a href="https://twitter.com/ScreenFlow">Screenflow</a></li><li><a href="https://www.descript.com/">Descript</a></li></ul><p>Ultimately, I chose Descript since, as a rookie, the ease of use and editing was most important to me. I didn't want something that would take me a week or, worst case scenario, a month to figure out how to use. I wanted something that would allow me to get up and running quickly, and Descript was designed just for that.</p><p>Descript allows you to edit videos just as you edit word documents: select and delete or copy and paste. Granted, other platforms have more advanced editing capabilities than Descript, but the ease of use and shorter time required to get started pulled me in. The subscription fee also wasn't a problem because my company would shoulder that.</p><p>You can also decide to use a combination of two or all tools, whatever works for you.</p><h2 id="step-2-understand-the-process">Step 2: Understand the Process</h2><p>Again, as a total newbie and novice, I had no idea what went into or what people did to produce tutorial videos on YouTube. How did they do it?</p><p>My friend <a href="https://twitter.com/_estheragbaje">Esther</a> was very helpful at this point. Esther is a volunteer developer advocate for the open-source library Chakra UI, and has made <a href="https://www.youtube.com/playlist?list=PLLh_woCGjyGoAjugrC_Rpl8UFzV3sP3Sf">some very cool short explanatory videos</a> in the past. I watched some of them and thought that's how I want my videos to look. So I booked a one-hour zoom session with Esther, and she talked me through her process.</p><p>I think at this stage, you should seek out others who have created videos similar to the ones you want to create and ask them about their process. Esther told me to:</p><ol><li>start with writing my script,</li><li>make video slides accompanied by preferred animations on Canva</li><li>download the video slides from Canva</li><li>Record your screen and voice as you talk through each video slide.</li><li>Finally, upload the recording to your chosen editing tool, and edit out the unnecessary parts.</li></ol><p>I didn't even know I could make videos and also add background music to video slides on Canva! That was a discovery.</p><figure class="kg-card kg-image-card"><img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Screenshot-2022-10-25-at-17.17.45.png" class="kg-image" alt="Musings from recording and editing my first YouTube video" loading="lazy" width="1620" height="1074"/></figure><h2 id="part-3-write-a-script">Part 3: Write a script</h2><p>A video script serves as the framework and foundation upon which everything else is built. It's a chronological run-down of speech and actions that you want to feature in your video. It's basically all the things you plan to say and do during the course of a video, written out in text.</p><p>For example, if you're going to halt mid-sentence to drink water, laugh, wink, or ring a bell, write it down in the precise order, you intend to do it. Make your script as specific and descriptive as possible. This will keep you from making so many mistakes and having to do fewer edits.</p><p>Here is a snippet of the script I wrote for one of my YouTube videos:</p><figure class="kg-card kg-image-card"><img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Screenshot-2022-10-27-at-14.02.29.png" class="kg-image" alt="Musings from recording and editing my first YouTube video" loading="lazy" width="1612" height="1130"/></figure><h2 id="step-4-record">Step 4: Record</h2><p>After writing your scripts, the next step is to record your video. Here are some tips to remember while recording scenes where you need to show your face and talk directly to the camera:</p><ul><li>Be relaxed: For my first YouTube video, I wasn't so comfortable speaking into a camera. Most people who watched the video could tell that I was nervous and that the performance wasn't natural. Don't be like me; try to relax, and if possible, rehearse a few times in front of a mirror to perfect your delivery.</li><li>Talk directly to the camera. As much as possible, try to keep your gaze level with the camera and talk directly to the camera as if you were giving advice to a real person on the other end.</li><li>Pause for some seconds when you make a mistake before giving that line or scene a second attempt. This will make for you to edit out such errors and for the edits not to look so awkward.</li></ul><p>Lastly, If your video requires you to code or run through a demo, start with a screen recording of the demo. Then edit or cut out the parts where you made mistakes, or things didn't go as planned. After you're left with a more polished and straightforward demo video, now it's time to record the voice-over for it (if any).</p><p>I know this sounds like too much work, and you're probably wondering why you can't just screen-record and do the voice-over simultaneously. I learned this the hard way. You know how things usually never go as planned when you're live coding? You'll inevitably fumble through several sentences and forget exactly what you intended to say at any given moment. As a result, you can wind up with a video where it's tough to edit specific frames to precisely match the timing of the required speech.</p><p>Recording your demo, then editing, and doing the voice-over last, affords you the greatest probability to precisely align your demo with the intended speech, as you can even read your exact script from a piece of paper or another screen.</p><h2 id="step-5-all-together-now-edit">Step 5: All together now, edit!</h2><p>Now that you have all your pieces and components ready, it's time to cut, join, trim, e.t.c till you arrive at something that looks good (not perfect). Remember, perfection is the enemy of progress. Your first video will not be the best, and you'll have to make more videos to improve. It's a process, so get that video out there quickly.</p><h2 id="final-words">Final words.</h2><p>And, that's a summary of how my foray into the world of YouTube went. If there's anything you want me to share about this process that I didn't cover, feel free to message me on Twitter.</p><p>Btw, if you want to see the two videos I made, they're <a href="https://www.youtube.com/watch?v=F97HeO8_XS4">here</a> and <a href="https://www.youtube.com/watch?v=kjw755sbOI0&amp;t=10s">here</a>…</p>]]></content:encoded></item><item><title><![CDATA[#TCCS8: Behind the scenes; what it took to write Docs for Developers with Jared Bhatti]]></title><description><![CDATA[If you know me, then you'll know how much I love the Docs for Developers book
[https://docsfordevelopers.com/]. I always say that there aren't a lot of
resources or books on documentation and technical writing process
[https://www.everythingtechnicalwriting.com/the-technical-writing-process/]. And
that's why I love Docs for Developers so much. It's one book on documentation
that takes its time to painstakingly provide steps to get you from point A to
point B, along with an accompanying use case ]]></description><link>https://www.everythingtechnicalwriting.com/writing-docs-for-developers-with-jared-bhatti/</link><guid isPermaLink="false">Ghost__Post__63566cf8a236c8001d93a55d</guid><category><![CDATA[Interviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Mon, 24 Oct 2022 11:09:00 GMT</pubDate><media:content url="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/JARED.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/JARED.png" alt="#TCCS8: Behind the scenes; what it took to write Docs for Developers with Jared Bhatti"/><p>If you know me, then you'll know how much I love the <a href="https://docsfordevelopers.com/">Docs for Developers book</a>. I always say that there aren't a lot of resources or books on documentation and <a href="https://www.everythingtechnicalwriting.com/the-technical-writing-process/">technical writing process</a>. And that's why I love Docs for Developers so much. It's one book on documentation that takes its time to painstakingly provide steps to get you from point A to point B, along with an accompanying use case story. As the authors rightfully described, it is "an approachable book about creating technical documentation".</p><p>For this episode of TCCS, I sat down with <a href="https://www.linkedin.com/in/jaredbhatti/">Jared Bhatti</a> (virtually, of course). Jared Bhatti, who is currently a Staff Technical Writer at <a href="https://waymo.com/">Waymo</a> (Waymo was established under Alphabet as an autonomous driving technology company from the Google self-driving car project), was the lead writer for Docs for Developers. Before joining Waymo, he'd been at Google for 14 years as a technical writer in different capacities and departments. For fun, Jared plays the Ukulele and Drums.</p><p>During our chat, Jared shared a wealth of knowledge as he discussed what it took to write the Docs for Developers book, his time at Google, and how he advanced to managerial positions. I hope you enjoy this episode as much as I enjoyed talking to Jared.</p><h2 id="me-please-introduce-yourself-and-tell-us-how-you-started-up-to-where-you-are-right-now">Me: Please introduce yourself, and tell us how you started up to where you are right now.</h2><p><strong>Jared</strong>: My name is Jared Bhatti. I have been a tech writer for approximately 16 years. I've always been interested in writing, and in school, I studied English composition and Electrical Engineering. After I graduated, I worked at various startups, many of which no longer exist. At these startups, I was mostly doing engineering work, but I was also doing some writing on the side.</p><p>One day, I posted my resume on Craigslist, looking for a job. Craigslist is a wildly popular forum in the Bay Area and is a good place to find a job. A recruiter from Google reached out to me and said, 'hey, you have this really interesting assorted set of experience. I think you'd be a great technical writer here at Google'. So I interviewed for the role and passed.</p><p>Before that, I had never worked a formal technical writing job, yet I found myself documenting Ads. I worked on that for a few years before switching to something closer to electrical engineering: documenting Google's hardware platform (our power distribution systems, the servers, networking fibers, and things like that). After a few years, I moved again to Google Cloud, where I helped start the Google Cloud technical writing team. I was the first manager there and grew the team considerably for seven years before moving to Waymo, where I currently document autonomous vehicles. So it's been a really exciting career journey. And along the way, I wrote Docs for Developers.</p><h2 id="me-you-have-no-prior-technical-writing-experience-prior-to-google-so-what-did-you-do-to-improve-your-technical-writing-skills-and-succeed-at-work">Me: You have no prior technical writing experience prior to Google. So, what did you do to improve your technical writing skills and succeed at work?</h2><p><strong>Jared</strong>: Oftentimes, when tech writers (who do not have engineering backgrounds) sit down to talk to engineers, their major challenge is a knowledge and terminology gap, which inhibits understanding.</p><p>That was my advantage: I was very comfortable with engineering and communication. My ability to sit down with engineers and easily comprehend all the information they dumped on me was my superpower. Even though I lacked formal expertise in organising information, I used that advantage to build trust, which was key to getting information from engineers.</p><p>I learned all of the other pieces along the way. And I was lucky to have some great mentors at Google who saw my potential and helped me improve as a tech writer. So now, when I mentor someone, I try to find out if they have more experience in writing or engineering and help them fill in the gaps.</p><h2 id="me-so-what-should-someone-with-more-writing-experience-do-to-close-the-technical-gap">Me: So what should someone with more writing experience do to close the technical gap?</h2><p><strong>Jared</strong>: I would recommend learning some fundamental programming language (Python or Ruby, or Javascript), and just learning enough to build a small app to get a basic understanding of how things are built.</p><p>While doing that, you may also get the opportunity to learn some of the modalities of technical writing based on some interesting resources you might find. Mm. For example, when I started learning Ruby, I discovered there's a really good free online graphic novel called 'The Poignant Guide to Ruby'. It's a fun way to learn Ruby through a cartoon mouse and a bunch of really cheesy jokes about bacon. That experience helped me see and learn a different format of tech writing.</p><p>I'd also suggest getting a mentor, and <a href="https://www.writethedocs.org/">Write the Docs</a> is an excellent place to find mentorship. I met all the people I wrote my book with through that community.</p><h2 id="me-after-working-within-google-for-over-14-years-what-prompted-your-move-to-waymo">Me: After working within Google for over 14 years, what prompted your move to Waymo?</h2><p><strong>Jared</strong>: The short story was that I felt I was due for a new challenge. After working on the cloud, where the hardware is not visible, I was yearning to do something more hardware-based again.</p><p>I wasn't planning to switch, but the opportunity came up, and I just went with it. Waymo had been looking for their first technical writer for about a year and a half, and they were looking for someone with very specific skills. One day, I got talking with the hiring manager, and as we talked, I realized that I might be the person they were looking for. I figured I could have a lot of impact here.</p><h2 id="me-so-do-you-get-a-personal-waymo-as-part-of-your-compensation-i-mean-since-you-have-to-test-it">Me: So, do you get a personal Waymo as part of your compensation? I mean, since you have to test it?</h2><p><strong>Jared</strong>: Hehehe. I get the joy of riding Waymo vehicles for free in San Francisco.</p><h2 id="me-i-imagine-you-didnt-know-much-about-waymos-technology-when-you-joined-so-what-did-you-do-to-get-the-necessary-knowledge-to-contribute-value-as-quickly-as-possible">Me: I imagine you didn't know much about Waymo's technology when you joined. So, what did you do to get the necessary knowledge to contribute value as quickly as possible?</h2><p><strong>Jared</strong>: Waymo actually does a pretty good job with onboarding engineers. When I joined, I went through the engineering onboarding, which is something tech writers should do. If your company has a non-technical onboarding and they try to push you to do that, don't do it. Do the engineering onboarding, since you'll be working with engineers. You need to know everything that they're doing.</p><p>One thing I did to contribute value, even while still in onboarding, was to find the gaps in onboarding. As a tech writer, you will discover communication gaps in your initial few days; trust your instincts on this. I noticed that different departments had their own glossaries and siloed docs. I took on consolidating all the individual glossaries, and when I did, everyone was like, 'wow! I don't know how we operated without this'. Now everyone can look up all company-wide terms from just one location.</p><h2 id="me-youve-been-a-technical-writing-manager-what-steps-must-a-senior-technical-writer-take-to-qualify-for-a-management-position">Me: You've been a technical writing manager. What steps must a senior technical writer take to qualify for a management position?</h2><p><strong>Jared</strong>: The first step is to understand that managing is very different from working as an individual contributor. You will be responsible for all the people reporting to you and doing a lot less technical writing. Instead, you'll be focused a lot more on coaching, mentoring, navigating organizational issues, having hard conversations, setting standards, and advocating for technical writing. And when you first start, you probably won't be very good at it.</p><p>I already mentioned Write the Docs. There's a whole group of tech writing managers in that Slack channel, and they're always asking each other questions about managing and giving each other feedback. That's a great place to learn and get help.</p><h2 id="me-lets-talk-docs-for-developers-when-did-you-get-the-inspiration-and-what-inspired-you">Me: Let's talk Docs for Developers. When did you get the inspiration, and what inspired you?</h2><p><strong>Jared</strong>: I got the inspiration to write a book because I found myself answering a lot of similar questions for people at Google and particularly in Kubernetes. Zachary Sarah and I were working with writers to onboard them into this open-source project, and we found ourselves giving the same advice over and over again. And so, Zachary suggested that we write a book on open-source docs.</p><p>As we started researching, we realized that the number of people who would buy a book about technical writing in general, was much higher than the number of people who would buy a book on open-source docs. And there also wasn't any good book on just technical documentation in general.</p><p>We also realized that we needed expertise outside of our own. So we started reaching out to folks that worked at startups like Heidi Waterhouse and Jen Lambourne. David was from Stripe, and their docs are amazing.</p><p>It also turned out that each one of us had a book in mind. So we took all those book proposals and kind of Frankensteined them into one book and cleaned it up a bit. And that was the proposal we went with.</p><h2 id="me-what-challenges-did-you-experience-while-pitching">Me: What challenges did you experience while pitching?</h2><p><strong>Jared</strong>: We experienced some challenges and pushbacks while pitching to publishers, one being the general notion that books with a lot of co-authors don't usually get written due to creative differences or infighting. This was strange to me because I thought it would be more compelling. After all, more writers meant more expertise, but it was actually less compelling to publishers.</p><p>To tackle that, we added another section to our pitch on how we planned on working together. The section detailed our process our decision-making process and how we planned to commit to completing the book on schedule.</p><p>Another challenge was that publishers wanted the book to be a 'Google process' book. For example, when we pitched to publishers like O'Reilly, they asked, "is this gonna be the Google process for technical writing?" We said, "No, it's just going to be a general guide to writing technical documents." And they said, "well, if this was a company book, we might be a little more interested." That was kind of a surprise for me. But, I think it's because they had published a number of books on different 'Google processes' that sold really well.</p><h2 id="me-how-did-you-combine-writing-this-book-and-keeping-your-full-time-job-care-to-share-your-scheduling-secrets">Me: How did you combine writing this book and keeping your full-time job. Care to share your scheduling secrets?</h2><p><strong>Jared</strong>: We were pretty bad with our initial schedule. We thought we would bang out this book in three or four months because we were all writers. In retrospect, It was an absurdly short timeline. Everyone I know who had written a technical book told me to give myself a year. And I was like, 'Oh no, we got this'. Well, we didn't.</p><p>What I ended up doing was scheduling, usually two days a week, and just sitting and writing for a couple of hours. Each of us was working on one or two chapters in the book and also agreed to peer review each other's chapters.</p><p>Then Sarah agreed to be the editor-in-chief to ensure all of the chapters had the same voice and tone because we all had distinct writing styles. That was our approach. And it worked pretty well and took us a year to write it.</p><h2 id="me-what-were-some-challenges-you-all-encountered-while-writing-the-book">Me: What were some challenges you all encountered while writing the book?</h2><p>One of the hardest things we had to do was figure out what was in scope and what wasn't. Different companies or teams will have specific docs or additional docs they'll need; How do we create a real-world example that everyone would relate to</p><p>David actually gets a lot of credit for drinking half a bottle of wine one night and cranking out a little story that we could sort of wrap the book around: the story of Corg.ly. From there, things kind of fell into place.</p><p>We also had a huge debate about information architecture because while it is really key to organizing information, it's an advanced topic. Our target audience was engineers who needed to create good documentation, maybe because they didn't have a technical writer on their team. So everything that was not going to be useful or too much needed to be cut off. In the end, we compromised on that one because it was so important that we kept a chapter, but we tried to keep it fairly light and point to other materials. We also made a lot of effort not to favor any tool because doc tools change, and they go out of date quickly.</p><p>That's it. There were no real personality conflicts. We actually had a lot of really good conversations, and I learned a ton from everyone I worked with.</p><p>The End……</p><p>Some last words…</p><ul><li>Docs for Developers is being translated into Japanese and will be out in February or March of next year. So if you want the book in Japanese, keep an eye out for that.</li><li>If anybody wants advice on how to write a technical book or pitch to publishers, Jared is willing to share his detailed process with you. Reach out on Twitter or LinkedIn.</li></ul>]]></content:encoded></item><item><title><![CDATA[Books that have helped me become a better technical writer]]></title><description><![CDATA[In a previous tech content creator interview with Elisa Sawyer
[https://www.everythingtechnicalwriting.com/debunking-popular-technical-writing-misconceptions/]
, a documentation engineer, she said something: "It's common for technical
writers to continue to improve their technical knowledge and skills.
Paradoxically, it's less common for technical writers to continue to reach for
advanced writing skills…….."

Many people believe that exceptional writing is an inborn talent; if you got it,
you go]]></description><link>https://www.everythingtechnicalwriting.com/technical-writing-books/</link><guid isPermaLink="false">Ghost__Post__63204556d22747001da5e372</guid><category><![CDATA[Getting Started]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Wed, 14 Sep 2022 06:45:48 GMT</pubDate><media:content url="https://res-4.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/tech-books.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-4.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/tech-books.png" alt="Books that have helped me become a better technical writer"/><p>In a previous <a href="https://www.everythingtechnicalwriting.com/debunking-popular-technical-writing-misconceptions/">tech content creator interview with Elisa Sawyer</a>, a documentation engineer, she said something: "It's common for technical writers to continue to improve their technical knowledge and skills. Paradoxically, it's less common for technical writers to continue to reach for advanced writing skills…….."</p><p>Many people believe that exceptional writing is an inborn talent; if you got it, you got it. If you don't, then you don't. As a result, most technical writers spend time learning technologies related to their craft but forget to take time to train their writing muscles. But that should not be the case.</p><p>Writing, like every other skill, can be developed. You can certainly take your writing skills from tolerable to advanced by consciously honing your writing skills. One thing that has helped me acquire better writing skills has been reading books related to the art of writing. So, today, I want to share 3 books that I've read that have impacted my technical writing abilities. P.S they're not all technical writing books, but I learned valuable tips.</p><h2 id="everybody-writes-by-ann-hadley"><a href="https://amzn.to/3BvPZmb">Everybody Writes by Ann Hadley</a></h2><p>Although primarily written from a content marketing point of view, I believe 'Everybody Writes' is a book every writer should read regardless of their niche. The tips shared in this book show you how to take your writing from basic to excellent.</p><p>This book covers how some blueprints for better writing and thinking, grammar rules, and tools to help you choose better words and craft better paragraphs. It is a how-to, hands-on book offering practical steps.</p><p>As Ann says, "we're all capable of producing good writing, or at least better writing, because writing well is part habit, part knowledge of some fundamental rules, and part giving a damn".</p><h2 id="docs-for-developers"><a href="https://amzn.to/3RTGOCg">Docs for Developers</a></h2><p>The authors of this book (5 of whom are very experienced and well-accomplished technical writers) sub-named this book 'A field guide to technical writing', and I think it lives up to that name. I first read this book when I started to foray into the world of technical documentation. This book features tips on how to write good tech docs. From understanding users' needs to publishing, measuring, and maintaining helpful developer documentation, this book demystifies the process of creating great developer documentation.</p><h2 id="they-ask-you-answer-by-marcus-sheridan"><a href="https://amzn.to/3qAXOBY">They Ask, You Answer by Marcus Sheridan</a></h2><p>This book is mainly about content marketing. However, I learned a lot about content strategy and how to leverage written content as a strategy for brand growth, which is a valuable skill for technical writers and every tech content creator, in general, to have. The book centers on the idea that education and help is the place your content should come from. It teaches you how to create content your target audience wants to know and is curious about — content they'll love and engage with.</p><h2 id="conclusion">Conclusion</h2><p>Reading, not just reading books, is a sure way to become a better writer. As my friend <a href="https://twitter.com/tamioladipo">Tami</a> says, "you have to read as much as you write". It could be reading articles, documentation, or white papers from your favourite tech writers or even fiction (in my case). When you read, read with the intent to improve your craft and observe how others write.</p><p>There are techniques, rules, and best practices for technical writing and writing in general. Reading helps you uncover those. Reading allows you to discover new grammar, expand your vocabulary, discover new writing styles/word choice strategies, and derive new ideas.</p><p>Do you have any book(s) that have impacted your writing skills? I'd love to hear them. Share with me <a href="https://twitter.com/_MsLinda">@mslinda</a> on Twitter.</p>]]></content:encoded></item><item><title><![CDATA[Much Ado about Documentation Structure]]></title><description><![CDATA[Alice has just joined a new team as their sole technical writer, and she has
been tasked with documenting a new product or software from scratch. She stares
into her computer screen, unsure of where and how to begin.

For many technical writers —like Alice —figuring out documentation structure can
be a source of initial confusion and overwhelm. What should you document? How
should you document it? And, where should things go? Once you figure out
structure, you'll have a sense of direction; once ]]></description><link>https://www.everythingtechnicalwriting.com/much-ado-about-software-documentation-structure/</link><guid isPermaLink="false">Ghost__Post__62fc9ff1f953d3001d796d58</guid><category><![CDATA[Content Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Wed, 17 Aug 2022 08:11:49 GMT</pubDate><media:content url="https://res-5.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/docs-structure.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-5.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/docs-structure.png" alt="Much Ado about Documentation Structure"/><p>Alice has just joined a new team as their sole technical writer, and she has been tasked with documenting a new product or software from scratch. She stares into her computer screen, unsure of where and how to begin.</p><p>For many technical writers —like Alice —figuring out documentation structure can be a source of initial confusion and overwhelm. What should you document? How should you document it? And, where should things go? Once you figure out structure, you'll have a sense of direction; once you have direction, everything's easier to start.</p><p>Structuring docs can be a very nuanced problem, and there's no one-size-fits-all that all software documentation projects can adopt. Regardless, no matter what approach you take, at a very high level, your documentation should be categorized logically, such that it intuitively answers 'where can I find information on how to do something?' for users and 'where do I put new information?' for other technical writers and contributors.</p><p>For me, two things I do to get a jump start on structure are follow common patterns of similar documentation projects and use templates for individual pages.</p><h2 id="follow-common-documentation-patterns">Follow common documentation patterns</h2><p>The reason behind this approach is simple: your users are not isolated. They've most definitely used and consulted several documentation and have grown accustomed to specific patterns and expectations. Don't try to reinvent the wheels and structure your docs differently. You'll only confuse your users and make it more difficult for them to find the answers they need. Look at projects that are similar to yours. How have they structured their documentation? Are there any similarities with your product? What can you copy? And, what can you improve?</p><p>Here's a basic structure I usually start from and then build on:</p><ol><li><strong>About the product</strong>: Brief introduction of the product covering what it does, who it is for, the pain point it helps users address, e.t.c. Many people will come to your docs to figure out what the software does. Someone will mention it, or they'll google a phrase randomly. You should explain what your software or company does and why it exists.</li><li><strong>Setup and installation</strong>: This does not need much introduction. What does one have to do to get up and running with the product or tool?</li><li><strong>Getting started tutorial</strong>. This tutorial should cover how to complete the single smallest, most common, or most important workflow for which users/developers use the product for. For a product like <a href="https://www.notion.so/product">Notion</a>, this could be something like creating your first page. For something like <a href="https://barter.me/">Barter</a>, it could be sending USD from your Nigerian naira account. And for something like <a href="http://stripe">Stripe</a>, it could be how to set up a simple checkout page to accept online payments.</li><li><strong>The rest of the documentation</strong>: The rest of the documentation can then either be categorised and split by target audience or use cases, features, or a combination, based on what works for your project.</li></ol><ul><li><strong>Usecases</strong>: Building on the getting started guide, the rest of the docs can be categorised into instructions or guides on individual tasks that users can accomplish with the software and how they can do so. For example, for a product like <a href="https://buycoins.africa/">Buycoins</a>, you'll be looking at other things that users can do on Buycoins to achieve their goals — things like withdraw funds, deposit funds, trade peer to peer, e.t.c</li><li><strong>Features &amp; Concepts: </strong> You can also decide to categorise the docs based on the different features of the software and how to perform various tasks with them. This is more relevant for SaaS products. For example, something like Notion has individual features like widgets, tables, databases, e.t.c. You could categorise your documentation per feature: what each feature is, when users may want to use them, and how users can complete various tasks with each feature (e.g: add a widget, remove a widget, build their own widget), e.t.c.</li><li><strong>Audience:</strong> You can also decide to group your docs based on different user profiles and features or information that is most specific to them. For example, some products are intended for use by end-users, developers, and designers too. This approach is adopted by the Readthedocs docs.</li></ul><figure class="kg-card kg-image-card"><img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Screenshot-2022-08-16-at-23.28.22.png" class="kg-image" alt="Much Ado about Documentation Structure" loading="lazy" width="2190" height="1214"/></figure><p>5. <strong>Resources</strong>: This section can contain community-contributed materials, projects, tutorials, examples of others using your product, e.t.c</p><p>6. <strong>FAQs</strong></p><h2 id="use-templates">Use Templates</h2><p>If you've figured out the structure of the entire documentation as a whole, the next thing you need to figure out is the structure of individual pages and different categories of content. Templates provide question checklists to show writers what information they should include, so they don't have to guess.</p><p>Using templates solves two problems. First, it enforces standardization (i.e., each page has the same structure) and so lowers the time it takes for users to search through documentation. The second reason to use templates is that it helps you and other contributors to quickly overcome the blank page dilemma.</p><p>Here are some resources you should check out to learn more about different document pages types and also see some established templates:</p><ul><li><a href="https://github.com/thegooddocsproject/templates">The Good Docs Project</a></li><li><a href="https://docs.gitlab.com/ee/development/documentation/structure.html">GitLab Documentation Topic Types</a></li><li><a href="https://www.gatsbyjs.com/contributing/docs-contributions/docs-structure/">Gatsby documentation types and templates</a></li><li><a href="https://documentation.divio.com/introduction/">Divo documentation guide</a></li></ul><h2 id="conclusion">Conclusion</h2><p>Just naming things in programming, documentation structure isn't the easiest thing to figure out. I hope this article provides you with a starting point from which you can evolve.</p><p><strong>Further reading:</strong></p><ul><li><a href="https://www.iodigital.com/en/history/foreach/defining-an-efficient-documentation-structure">Defining an efficient documentation structure</a></li></ul>]]></content:encoded></item><item><title><![CDATA[Google Season of Docs: Everything you need to know to get accepted (TCCS #7)]]></title><description><![CDATA[The Tech Content Creator Series (TCCS) is a monthly interview series in which I
chat with people in technical content creation roles (technical writers,
documentation engineers, developer advocates, and what have you) about their
careers. My hope is for their stories to impact, inspire, and motivate you.

The Google Season of Docs is an annual paid internship program by Google that
allows technical writers to work on open source projects worldwide. The goal is
to help improve the technical docum]]></description><link>https://www.everythingtechnicalwriting.com/get-into-google-season-of-docs/</link><guid isPermaLink="false">Ghost__Post__62f519c630f23d001d54170e</guid><category><![CDATA[Interviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Thu, 11 Aug 2022 15:53:41 GMT</pubDate><media:content url="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/GSOD.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/GSOD.png" alt="Google Season of Docs: Everything you need to know to get accepted (TCCS #7)"/><p><em>The Tech Content Creator Series (TCCS) is a monthly interview series in which I chat with people in technical content creation roles (technical writers, documentation engineers, developer advocates, and what have you) about their careers. My hope is for their stories to impact, inspire, and motivate you.</em></p><p>The Google Season of Docs is an annual paid internship program by Google that allows technical writers to work on open source projects worldwide. The goal is to help improve the technical documentation of open source projects and also give technical writers a chance to actively contribute to open source.</p><p>For this month's <a href="https://www.dropbox.com/?q=%23TechContentCreatorSeries">#TechContentCreatorSeries</a>, I decided to do something a bit different. Instead of chatting with just one person, I reached out to three current Google Season of Docs interns (Amarachi, Nelson &amp; Funke). They answered some crucial questions and gave tips you should check out if you're hoping to get accepted into Google Season of Docs too!</p><h3 id="key-takeaways">Key Takeaways:</h3><ul><li>Everything you need to know about the application process is on the <a href="https://developers.google.com/season-of-docs">Google Summer of Docs</a> website.</li><li>Try to understand the organization and its proposal correctly before applying. Show them that you have a good overview of what you're getting into.</li><li>Active open source contribution and participation prior to the selection phase increases your chances of acceptance. Try to contribute to the project and also be involved in the organization's slack, discord, or whatever channel they use for communication.</li><li>Prior technical writing experience also increases your chances of acceptance. Have a technical writing portfolio of some sort.</li></ul><h2 id="q-first-of-all-introduction">Q: First of all, introduction?</h2><p><strong>Amarachi:</strong> My name is Amarachi Iheanacho. I am a technical writer working with <a href="https://moja.global/">Moja Global</a> for this year's GSOD. Moja global helps mitigate the adverse effects of climate change by creating software to correctly estimate greenhouse gas emissions and removals from forestry, agriculture, and land uses(AFOLU).</p><p><strong>Funke</strong>: I am Funke Faith Olasupo. I am a Backend Developer and Technical Writer. I am interning at <a href="https://world.openfoodfacts.org/"><u>Open Food Facts</u></a> for GSOD'22. Open Food Facts is an open food product database that helps people make better food choices.</p><p><strong>Nelson:</strong> Hi, I'm Nelson Michael. I am a front-end developer/ technical writer, currently interning with <a href="https://www.asyncapi.com/">AsyncAPI</a> for this year's GSOD program. AsyncAPI provides the AsyncAPI specification for asynchronous APIs and a set of tools for you to easily build and maintain an Event-Driven-Architecture(EDA). Essentially the AsyncAPI specs are to asynchronous APIs what the OpenAPI specs are to REST APIs.</p><h2 id="q-how-did-you-get-interested-in-technical-writing-and-documentation">Q: How did you get interested in technical writing and documentation?</h2><p><strong>Amarachi</strong>: I started writing technical articles because of a piece of random advice on Twitter. I discovered that writing articles not only helped me grasp technical topics better but also gave me clout. Writing articles on a subject demonstrates that I understand that subject.</p><p><strong>Funke</strong>: It all started with a desire to document the bugs I encountered while coding and how I solved them so that others could learn from them.</p><p><strong>Nelson:</strong> A friend sparked my interest in technical writing. He was writing a lot at the time, and I was curious. So, I reached out to him to help me get started. With his help, I wrote and published my first article on my blog, and I've just continued on the path since.</p><h2 id="q-what-motivated-you-to-apply-for-the-google-season-of-docs-program-and-how-did-you-decide-which-project-to-apply-to">Q: What motivated you to apply for the Google Season of Docs program, and how did you decide which project to apply to?</h2><p><strong>Amarachi</strong>: I applied because I wanted to go into DevRel, and the opportunity to create documentation and contribute to open source would be a plus on my resume. Moja Global's plans and efforts for their potential technical writer appeared interesting, so I applied to join them.</p><p><strong>Funke</strong>: I have always wanted to move away from making minute contributions to being an integral part of an open source project. GSOD sounded like the perfect opportunity for that. Then there's also the pay; nothing beats getting paid to contribute to open source. On applying to orgs, I looked through all the accepted organizations and checked for the organizations whose goals I could resonate with. I also checked their accepted proposal on what they wanted to achieve by the end of this year's GSOD program. Then, I applied to the ones I could relate to.</p><p><strong>Nelson</strong>: I applied to GSOD for two reasons. I knew it would be an excellent opportunity to learn how documentation works. Also, I knew that having GSOD on my resume would definitely expose me to more opportunities. For my decision to apply to AsyncApi, they made it clear that it would be a learning process, so anyone could apply regardless of their writing experience. I had zero knowledge of documentation, so I figured it would be a good learning experience.</p><h2 id="q-what-was-your-application-process-like-and-what-did-you-do-differently-to-ensure-your-selection">Q: What was your application process like? And, what did you do differently to ensure your selection?</h2><p><strong>Amarachi:</strong> To earn a spot as a technical writer, we were asked to create technical articles on complex topics like state and transition models, FLINT, etc. I made sure to break down the concepts like I was speaking to a five-year-old. Also, I previously contributed to Moja's Global documentation via a <a href="https://shecodeafrica.org/">SheCodeAfrica</a> program called "<em>Contributhon</em>". I think it is essential to contribute to an organization's open-source project beforehand to give you an edge.</p><p><strong>Funke</strong>: I had an interview for two different organizations, and sadly the first didn't pick me. While applying for Open Food Facts, I simply explained how their futuristic goals aligned with mine and how my skill set would benefit the project. Above all, a foodie working on a food project, what enthusiasm!</p><p><strong>Nelson:</strong> After applying and before my interview, I decided to get involved. I started engaging on the slack channel, answering questions, having discussions, some community calls, and all that stuff just so that my name was a regular. I also made sure I contributed to the project even before the program started. I had a PR merged and raised some issues too. I just made sure I was visible and present.</p><h2 id="q-were-you-required-to-submit-a-proposal-if-yes-what-resources-or-tips-did-you-consult-to-write-your-proposal">Q: Were you required to submit a proposal? If yes, what resources or tips did you consult to write your proposal?</h2><p><strong>Amarachi</strong>: Yes. I drew inspiration from <a href="https://docs.google.com/document/d/1sjHn5OGVZB0EbWHFL9_9Ty63oCF2itlYww2bf9Qhwtc/edit?usp=sharing"><u>Edidiong Asikpo's </u></a>and <a href="https://phabricator.wikimedia.org/T255360">Gbadebo Bello's</a> proposals.</p><p><strong>Funke</strong>: Yes. <a href="https://chaoss.community/"><u>CHAOSS </u></a> made interested applicants put their proposals in a public Github repo. I also through those to draw inspiration. When writing a proposal, I would advise everyone to avoid a generalized proposal and state their proposed solution after reviewing the existing documentation of the organization. Your proposed solutions should also tackle the organization's goals for that year's GSOD. Also, remember to highlight your experience as a technical writer and how it will be an excellent tool for improving documentation.</p><p><strong>Nelson:</strong> No, the org didn't ask for it. That's why I made sure I got involved in the community.</p><h2 id="q-what-are-some-of-the-challenges-youve-encountered-on-the-quest-to-achieve-your-project-goals-and-how-have-you-overcome-them">Q: What are some of the challenges you've encountered on the quest to achieve your project goals, and how have you overcome them?</h2><p><strong>Amarachi:</strong> One of the challenges I encountered was finding and understanding the source materials. I have since learned that the solution is to ask questions, ask for resources, ask what the tasks actually mean, and ask for feedback. Also, I found that some tasks can be overwhelming, so it's a good idea to break the big tasks into smaller tasks that I can tackle without losing my mind.</p><p><strong>Funke</strong>: I was tasked with drafting an Open API file which was new for me. Before that, all I've done is write articles and regular API documentation. I didn't even know what OpenAPI was or how to get started. So far, I've found my way around by asking questions and researching. I reach out to mentors in the organization and senior technical writers. I am currently building the Open API file for this project, and I love every bit of the journey!</p><p><strong>Nelson:</strong> My biggest blocker at the time was understanding what the whole project was about. I had no idea what an Event-Driven-Architecture(EDA) is. My mentors put together an onboarding video for us where they did an introduction to EDAs, which was quite helpful. I also did a lot of research that helped clear up many things for me. My challenge right now is creating diagrams with mermaid.js; I'm still learning the ropes.</p><h2 id="q-what-has-your-experience-been-like-what-skills-have-you-picked-up-and-what-have-you-learned">Q: What has your experience been like? What skills have you picked up, and what have you learned?</h2><p><strong>Amarachi:</strong> My experience has been great. I am learning to write better documentation, read large and relatively complex resources and effectively communicate what they mean in a beginner-friendly manner. I have also brushed up on my learning skills (i.e., how to learn effectively).</p><p><strong>Funke</strong>: It's been a rollercoaster. <a href="https://twitter.com/_MsLinda"><u>Linda Ikechukwu</u></a>, one of the mentors I reached out to when starting my first task, introduced me to a course on <a href="https://idratherbewriting.com/learnapidoc/"><u>API documentation</u></a> that guided me into the first few phases of my tasks. I have also learned to communicate better because I work with a relatively large team. Above all, I have the opportunity to explore and deeply understand API documentation.</p><p><strong>Nelson:</strong> It's been great. There have definitely been some challenges, but overall it's been an amazing experience. I always thought you could just write a bunch of articles explaining stuff about a project, slap it together, and you have documentation. Now I think about it differently. I now realize the importance of good structure and information architecture when creating documentation.</p><h2 id="q-what-does-the-future-look-like-for-you-after-gsod-what-are-your-plans">Q: What does the future look like for you after GSOD? What are your plans?</h2><p><strong>Amarachi:</strong> After GSOD, I hope to get into developer relations engineering. I hope my background in software engineering, technical writing (especially documentation), and not to mention community building helps me as I journey down that path.</p><p><strong>Funke</strong>: After GSOD, I plan to work as a full-time technical writer. I also plan to use these improved skills to contribute to other open source organizations to help improve their documentation.</p><p><strong>Nelson:</strong> Well, I've been holding off applying for jobs in the Dev Rel space because I wanted GSOD on my portfolio, so after this program, it's trying to get a full-time Dev Advocate role for me.</p><p>More resources to learn more about GSOD</p><ul><li><a href="https://docs.google.com/presentation/d/1An3Y2hWmbJnRUcJ8Vn17dIM4lXUvziOqooBx64e-WKE/edit#slide=id.g11a712d418c_1_6">Google Season of Docs: What is it and how to get in </a>(A talk)</li><li><a href="https://edidiongasikpo.com/how-to-crack-the-google-season-of-docs-application-process-for-2020">How to Crack the Google Season of Docs Application Process</a></li></ul>]]></content:encoded></item><item><title><![CDATA[TCCS #6: How to handle managers who do not understand the technical writing role (+ Debunking common myths about Technical Writing)]]></title><description><![CDATA[The Tech Content Creator Series is a monthly interview series in which I chat
with people in technical content creation roles (technical writers,
documentation engineers, developer advocates, and what have you) about their
careers. My hope is for their stories to impact, inspire, and motivate you.

For this episode, I spoke to Elisa Sawyer
[https://www.linkedin.com/in/elisasawyer/] who is a Documentation Architect with
over 20 years of extensive technical writing experience. As a technical write]]></description><link>https://www.everythingtechnicalwriting.com/debunking-popular-technical-writing-misconceptions/</link><guid isPermaLink="false">Ghost__Post__62c6d86f88c11a001dcc2692</guid><category><![CDATA[Interviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Thu, 07 Jul 2022 23:37:41 GMT</pubDate><media:content url="https://res-4.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/techcontentseries5.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-4.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/techcontentseries5.png" alt="TCCS #6: How to handle managers who do not understand the technical writing role (+ Debunking common myths about Technical Writing)"/><p><em>The Tech Content Creator Series is a monthly interview series in which I chat with people in technical content creation roles (technical writers, documentation engineers, developer advocates, and what have you) about their careers. My hope is for their stories to impact, inspire, and motivate you.</em></p><p>For this episode, I spoke to <a href="https://www.linkedin.com/in/elisasawyer/">Elisa Sawyer</a> who is a Documentation Architect with over 20 years of extensive technical writing experience. As a technical writer, she has worked with several high-tech companies like Google, Uber, Apple and Visa. She's also an avid member of the <a href="https://www.writethedocs.org/">writethedocs</a> slack community. </p><p>We chatted briefly about how she got into technical writing, what to do when you find yourself working with managers who don't understand the role of technical writers, and also debunked some popular technical writing myths.</p><p>Enjoy!</p><h2 id="can-you-briefly-introduce-yourself">Can you briefly introduce yourself?</h2><p>My name is Elisa Sawyer, and I work as a Documentation Architect. My mother was a concert pianist, and my father was a PhD physicist. My siblings and I watched the local orchestra as if it was a spectator sport and thought the latest in particle physics was what everyone discussed over Saturday barbecue. I love mathematics, sciences, and the arts equally.</p><h2 id="how-did-you-get-into-technical-writing-and-developer-documentation-did-you-get-a-writing-degree-from-a-university-if-you-did-what-impact-did-it-have-on-your-career">How did you get into technical writing and developer documentation? Did you get a writing degree from a university? If you did, what impact did it have on your career?</h2><p>I was a grant proposal writer for many years before I decided to apply my writing skills to writing for high-tech companies. My Master's degree is in Urban Studies. However, I got a certificate in tech writing that helped me get my first contract for a Silicon Valley company. Later, I enrolled in screenwriting classes through <a href="https://www.uclaextension.edu/writing-journalism">UCLA Extension Writers’ Program</a>.</p><p>The technical writing certificate program I enrolled in does not exist anymore. But, I've heard good things about the following programs: </p><ul><li><a href="https://extension.berkeley.edu/public/category/courseCategoryCertificateProfile.do?method=load&amp;from=courseprofile&amp;certificateId=17211&amp;b_source=google&amp;b_medium=cpc&amp;b_campaign=11004879302&amp;b_adgroup=116545739228&amp;b_keyword=technical%20communication%20certificate&amp;b_matchtype=b&amp;b_gclid=CjwKCAjwiJqWBhBdEiwAtESPaMvd-hc0niXYCYGr48SIDRNrC1wiaVclIWapF2nQ4Gto4snjvh28XRoCOQ0QAvD_BwE&amp;b_device=c-&amp;b_position=&amp;b_adid=461240088608&amp;b_placement=&amp;b_random=222560278583141157&amp;gclid=CjwKCAjwiJqWBhBdEiwAtESPaMvd-hc0niXYCYGr48SIDRNrC1wiaVclIWapF2nQ4Gto4snjvh28XRoCOQ0QAvD_BwE">UC Berkeley Extension program on Technical Communication</a></li><li><a href="Certificate Program in Professional and Technical Writing | Department of English          and Comparative Literature">San Jose University program on Professional &amp; Technical Writing Communication</a></li><li><a href="https://explore.suny.edu/programs/buffalo-state-college-technical-writing-undergraduate-certificate-1700000000078">Buffalo State College Technical Writing Undergraduate Certificate</a></li></ul><h2 id="on-the-writethedocs-slack-channel-you-once-shared-an-experience-of-interviewing-with-managers-who-did-not-understand-a-technical-writers-role-are-there-any-tips-you-can-offer-to-a-technical-writer-who-finds-themselves-in-a-similar-situation">On the writethedocs Slack channel, you once shared an experience of interviewing with managers who did not understand a technical writers' role. Are there any tips you can offer to a technical writer who finds themselves in a similar situation?</h2><p>I have sometimes had people assume that I should have HTML or JavaScript tags memorized because I write developer-facing documentation. Once, a developer actually thought that I should know how to hand-code HTML. Although I understood his thinking, he made a false assumption and was so arrogant in his ignorance that there was no opportunity to illuminate his understanding of our profession.</p><p>For anyone who finds themselves in a similar situation, I don't think there is a single set of guidelines on dealing with managers and team members who don't understand technical writing because all teams have their own culture.</p><p>Dispelling common myths associated with the tech writing profession might be helpful in some situations. In addition, pointing to authoritative information on best practices for tech writing, along with conferences for both tech writers and tech writing managers, can be helpful. Some managers/team members actually respond well to helpful tips, and those who don't respond well might simply need time for the information to sink in.</p><p>Additionally, during an interview, it is sometimes helpful to ask what problems the manager hopes the writer can solve. The managers' answers to this question can provide information that will help you decide whether you are a good fit.<br>I have been a contract worker for a long time, so I can't comment on the interview processes for full-time positions. I think that managers and writers involved in interviews for contract roles are able and willing to take risks.</br></p><h2 id="what-are-the-common-myths-or-misconceptions-about-the-technical-writing-career-that-youve-encountered">What are the common myths or misconceptions about the technical writing career that you've encountered?</h2><p><strong><em>Myth #1: “Why do we need technical writers when developers write self-documenting code.” </em></strong></p><p><strong>Comment:</strong> While you can write code with parameters that are easy to understand, I have never encountered a situation where new hires just sit and read through an uncommented code base to quickly understand it.</p><p><strong><em>Myth #2: “We can just wait until the documentation arrives.”</em></strong> </p><p><strong>Comment</strong>: I was working through a gnarly procedure to write the documentation for several teams of developers when my subject-matter expert made the above comment. I reminded him that if I didn't write it, the documentation would not arrive.</p><p><strong><em>Myth #3: “The docs are basically what we (engineers) told you.” </em></strong></p><p><strong>Comment</strong>: A developer commented, in a derogatory way, that the documentation I'd written accurately reflected the information the team gave me. He should have understood that what he said was a compliment, not an insult. The difference between the information the team provided and what I wrote based on their information is that before my work, no one outside the team could effectively understand and use the features they were providing. I organized and documented everything so that even within their own team, everyone better understood how to use the features they offered.</p><p><strong><em>Myth #4: “Technical writers are basically glorified admins.”</em></strong> </p><p><strong>Comment</strong>: While it’s possible to enter the technical writing profession without a college degree and succeed, technical writing is an actual profession for which we can get advanced degrees. We are often functioning above our degree level. The best technical writers are dedicated to lifelong learning.</p><p><strong><em>Myth #5: “Just pretty things up, and the docs will become better.” </em></strong></p><p>Comment: While good graphics, layout, fonts, and other visual elements can make the communication experience pleasant, great technical writing is much more than pretty.</p><h2 id="do-you-think-someone-without-a-writing-degree-can-have-a-great-technical-writing-career-also-do-you-think-someone-focused-on-developer-documentation-should-understand-how-to-code-or-how-it-works">Do you think someone without a writing degree can have a great technical writing career? Also, do you think someone focused on developer documentation should understand how to code or how it works?</h2><p>What you need as a writer are good analytic, problem-solving, and writing skills. Success in writing good developer-facing documentation does not depend on knowing how to code.</p><p>As a writer, you are <em>not</em> generally solving the same problems as full-time coders. Solving coding problems is the domain of full-time coders. Solving communication problems is the domain of the communications professional.</p><p>Also, as a contract technical writer, I have observed that there are many software developers who are confused about the role of the technical writer who focuses on developer-facing documentation. If great developer-facing documentation was easy to write, it would definitely be far more common.</p><h2 id="technical-writers-are-often-writing-about-things-they-know-nothing-about-could-you-share-some-tips-for-how-beginner-technical-writers-could-get-comfortable-or-get-better-at-writing-about-things-they-know-nothing-about">Technical writers are often writing about things they know nothing about. Could you share some tips for how beginner technical writers could get comfortable or get better at writing about things they know nothing about?</h2><p>Have you ever gotten excited about something that was new to you, and wanted to share your excitement?</p><p>Perhaps you decided to do something exciting and unusual like a hot air balloon ride, a cave tour, or kayaking for the first time. You tend to naturally be very aware of everything around you when you are going through that new experience. Because of that heightened awareness, it can be easy to remember many details about the experience.</p><p>That kind of heightened awareness of a new environment can help us as technical writers when we are writing about a new subject. We can write authentically about learning a new technology while learning it ourselves.</p><h2 id="lastly-do-you-have-any-other-general-tips-or-words-of-advice-you%E2%80%99ll-like-to-give-technical-writers-regarding-interviewing-and-excelling-in-their-careers">Lastly, do you have any other general tips or words of advice you’ll like to give technical writers regarding interviewing and excelling in their careers?</h2><p>It's common for technical writers to continue to improve their technical knowledge and skills. Paradoxically, it's less common for technical writers to continue to reach for advanced writing skills. I have found that taking classes in both fiction writing and writing screenplays for feature films has helped me become a better technical writer. My advice is to treat our profession as any other profession that requires continuing education, and regularly treat yourself to educational opportunities.</p>]]></content:encoded></item><item><title><![CDATA[My self editing checklist for technical writing]]></title><description><![CDATA[Professional editors are like interior designers. They can take the most basic
piece of writing and enhance it to become the best version of itself.

I first worked with an editor when I started writing for FreeCodeCamp
[https://www.freecodecamp.org/]. Since then, I have worked with several editors,
and I attribute the improvement I've seen in my writing to them.

However, as vital as editors are, you may not always have access to them for
various reasons. Perhaps, you're working as a lone tech ]]></description><link>https://www.everythingtechnicalwriting.com/my-self-editing-checklist-for-technical-writing/</link><guid isPermaLink="false">Ghost__Post__62baf66f2e91b6001dadfa21</guid><category><![CDATA[Content Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Mon, 04 Jul 2022 08:58:00 GMT</pubDate><media:content url="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/self-editing.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/self-editing.png" alt="My self editing checklist for technical writing"/><p>Professional editors are like interior designers. They can take the most basic piece of writing and enhance it to become the best version of itself.</p><p>I first worked with an editor when I started writing for <a href="https://www.freecodecamp.org/">FreeCodeCamp</a>. Since then, I have worked with several editors, and I attribute the improvement I've seen in my writing to them.</p><p>However, as vital as editors are, you may not always have access to them for various reasons. Perhaps, you're working as a lone tech writer, and your company does not have the budget to hire or contract an editor, or you're writing for your personal blog. In such situations, self-editing becomes an invaluable skill.</p><p>In addition to the benefit of being able to polish up your work in the absence of a professional editor, self-editing is a valuable skill to learn because it helps you become a better writer. As you practice self-editing, identifying the errors you make frequently and fixing them, the quality of your writing will improve.</p><h2 id="my-self-editing-process">My self-editing process</h2><p>Taking a break (preferably a day) after writing my first draft is the first step in my editing process. This break allows me to properly rest my mind so I can approach editing with a fresh mind. Hence, it's advisable to write your first draft early (within the confines of your deadline), so you'll have enough time to take a break and return to self-edit.</p><p>When I eventually start self-editing, I begin by re-reading my draft and consider if there are ways I might restructure sections or paragraphs to make the flow more logical. I may use a tool like <a href="https://quillbot.com/">quillbot</a> or <a href="https://www.wordtune.com/">wordtune</a> to reword/rewrite paragraphs that don't sound right to me until they do.</p><p>When I'm satisfied with the draft's content and flow, I'll move on to sentence-level editing, looking for ways to make my sentences more straightforward, concise, and free of ambiguity. To help, I use <a href="https://lindaikechukwu.notion.site/My-personal-technical-writing-editing-checklist-bd72f5a659994840933df93fb1b8f560">this self-editing checklist</a> which I put together.</p><figure class="kg-card kg-bookmark-card kg-card-hascaption"><a class="kg-bookmark-container" href="https://lindaikechukwu.notion.site/My-personal-technical-writing-editing-checklist-bd72f5a659994840933df93fb1b8f560"><div class="kg-bookmark-content"><div class="kg-bookmark-title">Notion – The all-in-one workspace for your notes, tasks, wikis, and databases.</div><div class="kg-bookmark-description">A new tool that blends your everyday work apps into one. It’s the all-in-one workspace for you and your team</div><div class="kg-bookmark-metadata"><img class="kg-bookmark-icon" src="https://lindaikechukwu.notion.site/images/logo-ios.png" alt="My self editing checklist for technical writing"><span class="kg-bookmark-author">Notion</span></img></div></div><div class="kg-bookmark-thumbnail"><img src="https://www.notion.so/images/meta/default.png" alt="My self editing checklist for technical writing"/></div></a><figcaption>Link to my self-editing checklist on Notion</figcaption></figure><p>The checklist includes common errors that I make. Every time I check my writing against this self-editing checklist, it comes out improved. At this point, I would also check my writing against a style guide if it applies to my situation.</p><p>As a final step, I run my writing through <a href="https://app.grammarly.com/">Grammarly</a> to catch any residual typos, grammar errors, and plagiarism occurrences.</p><p>I also shared some editing tips in two previous posts: <a href="https://www.everythingtechnicalwriting.com/the-technical-writing-process/">the technical writing process</a> and <a href="https://www.everythingtechnicalwriting.com/how-to-write-content-that-readers-will-read/">how to write content that your readers will thank you for</a>. </p><div class="kg-card kg-callout-card kg-callout-card-purple"><div class="kg-callout-emoji">💡</div><div class="kg-callout-text">Remember not to go overboard with self-editing. If you become obsessed with making your draft perfect in every way, you’ll never be done and will never publish. Set a deadline and an acceptable number of edits (say, 2) and consider the work completed. As Leonardo da Vinci said: "Art is never finished but abandoned".</div></div>]]></content:encoded></item><item><title><![CDATA[A Technical Writer's Introduction to Docs as Code]]></title><description><![CDATA[Documentation (especially developer documentation) flourishes when people
(especially developers) outside the tech writing team can easily review or
contribute to it. This is because tech writers cannot know everything worth
knowing about an application, SDK, or API.

Traditional web publishing involves using CMSs ( content management systems) or
HATs (help authoring tools) like WordPress. The problem is that when such tools
are used to manage and publish documentation, it's difficult for people]]></description><link>https://www.everythingtechnicalwriting.com/dosc-as-code/</link><guid isPermaLink="false">Ghost__Post__62b5f028b5e934001d5df5f9</guid><category><![CDATA[Getting Started]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Wed, 29 Jun 2022 14:52:00 GMT</pubDate><media:content url="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/docs-as-code.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/docs-as-code.png" alt="A Technical Writer's Introduction to Docs as Code"/><p>Documentation (especially developer documentation) flourishes when people (especially developers) outside the tech writing team can easily review or contribute to it. This is because tech writers cannot know everything worth knowing about an application, SDK, or API.</p><p>Traditional web publishing involves using CMSs ( content management systems) or HATs (help authoring tools) like WordPress. The problem is that when such tools are used to manage and publish documentation, it's difficult for people outside the tech writing team to contribute because of the limited access and authentication hurdles of the admin portal of such tools.</p><p>This need for an easier way to foster collaboration and contribution to documentation projects gave rise to the docs-as-code approach.</p><p>In this article, I'll briefly go over what docs-as-code is, when to adopt it, its benefits, and the tools you need to set up a docs-as-code pipeline.</p><h2 id="what-is-docs-as-code">What is Docs as Code?</h2><p><em>Docs as Code</em> refers to writing, publishing, and managing docs using the same tools and workflows developers use to write and publish code. Developers have already hacked code contribution and collaboration using tools like git and GitHub, and also automation with CI/CD pipelines. </p><p>By adopting docs-as-code, documentation teams can leverage the same ease of collaboration and automation that developers implement for source code.</p><h2 id="when-to-adopt-docs-as-code">When to adopt Docs as Code?</h2><p>The question of when to adopt docs as code is best answered by a question I was asked by a Google Season of Docs (GSOD) intern. </p><p>She asked (and I paraphrase): "<em>My fellow interns and I are working on a documentation project. How can we set up our documentation project such that by the end of the GSOD internship, if people stumble on a fix, they can contribute via Github pull request, and once it is merged, it will be automatically published in the docs?</em>".</p><p>If you find yourself with a similar need, then you need to adopt a docs-as-code approach. As the open-source developer community has taught us, developers are more than happy to contribute to projects they like or use.</p><h2 id="benefits-of-docs-as-code">Benefits of docs as code</h2><p>The primary benefit of the docs-as-code approach is that it fosters easier collaboration, as it brings your documentation closer to developers and the public.</p><p>If you're working on developer docs and require developers to either write the initial docs or review them, using tooling and familiar processes empowers them to contribute and participate more fully with the documentation authoring and publishing.</p><p>Other benefits of the docs as code approach include:</p><h3 id="automation">Automation: </h3><p>With the docs-as-code workflow, you can leverage automation usually implemented for code. </p><p>For example, you can create automated checks to run at every pull request to detect things like technical errors (i.e., invalid links, invalid code snippets, etc.) or language errors (i.e., typos, missing punctuation, etc.) using natural/human language linters such as <a href="https://github.com/btford/write-good">writegood</a>, <a href="https://github.com/errata-ai/vale">vale</a>, or <a href="https://github.com/aim42/htmlSanityCheck">htmlSanityCheck</a>. </p><p>If the tests fail, the contributor is notified to rectify the errors. If the tests pass, a member of the tech writing team can manually review and merge. Then, once a change is merged to the main branch, the docs site gets updated with the pull request changes. This way, quality is still maintained even though everyone can contribute to the docs.</p><h3 id="customizations">Customizations: </h3><p>As long as you, the technical writer, is familiar with programming or has a developer willing to help out, the docs-as-code route allows one to customize their workflow as they deem fit for lesser costs. If you can think and code it, you can have it.</p><h3 id="transparency-and-easier-tracking">Transparency and easier tracking: </h3><p>Thanks to the versioning feature of git and the issue feature of code repository tools like GitHub and GitLab, one can easily track progress and every change made to the documentation. That way, in the event of an error, it's easy to roll back.</p><h2 id="components-of-a-docs-as-code-setup">Components of a Docs as Code setup</h2><p>To set up docs-as-code, you need 4 primary components: version control (git and a web-based git platform like GitHub, GitLab, Bitbucket), a static site generator, a CI/CD pipeline, and a web hosting platform.</p><h3 id="git">Git:</h3><p>Using git and a web-based git platform like GitHub to manage the content of a documentation site facilitates the ease of collaboration that is a core benefit of the docs-as-code approach. It allows for offline and concurrent work on the same file from different people.</p><p>When choosing what git platform to go for, go for what developers in your company are already using.</p><h3 id="static-site-generators">Static site generators:</h3><p><a href="https://www.netlify.com/blog/2020/04/14/what-is-a-static-site-generator-and-3-ways-to-find-the-best-one/">Static site generators</a> (SSGs) are programs that take content and themes (templated HTML and CSS), process them, and output a folder full of all the resultant pages and assets.</p><p>The appeal of SSGs is that, unlike with traditional web application stack, layout code is decoupled from the content in the form of themes. Also, the content is usually written with plain markup languages like Markdown or reStructuredText. This makes it easier for anyone to contribute as they only have to worry about the accuracy of the content and not how it will look.</p><p>The second appeal of SSGs is that, unlike traditional web application stack, which waits until a page is requested before it generates it, SSGs build all the individual pages ahead of time, so response times are faster. And, fast page load times mean better documentation experience.</p><p>Also, since SSGs usually process and output everything as simple HTML pages, hosting static websites is simpler. You can host static websites practically anywhere with the simplest web servers like Amazon S3 or GitHub Pages. My favourite web hosting platform is Netlify because of its inbuilt automation features.</p><p>In choosing which SSG to use, consider what languages and frameworks your development team already uses, so nobody has to learn a whole new language. For example, if your development team primarily leans towards JavaScript, you should consider JavaScript-based SSGs and themes. Also, consider what features you need for your documentation site. Some static site generators are explicitly built for blog pages, while others are specially built for the needs of documentation sites.</p><p>Examples of SSGs to choose from are <a href="https://github.com/slatedocs/slate/wiki#getting-started">SlateDocs</a> (for API Documentation), <a href="https://www.mkdocs.org/">MkDocs, Docsify</a>, <a href="https://www.sphinx-doc.org/en/master/">Sphinx</a>, <a href="https://docusaurus.io/">Docsarus</a>, <a href="https://www.gitbook.com/">Gitbook</a>, etc. Check out the <a href="https://jamstack.org/generators">staticgen</a> website for other SSGs that you can use.</p><h3 id="cicd-pipeline-or-workflow">CI/CD pipeline or workflow:</h3><p>A CI/CD (continuous integration and continuous delivery) is what affords us the automation that is a core benefit of docs as code. With a CI/CD workflow, you can write event-driven scripts to run automatic validation checks and deployment of your documentation site, as discussed above. Check this article to <em>learn how to <a href="https://www.smashingmagazine.com/2021/08/automate-documentation-workflow-for-developers/">automate your documentation workflow with Vale and GitHub Actions</a>.</em></p><h3 id="web-hosting-platform">Web hosting platform:</h3><p>There isn't much to discuss in terms of web hosting platforms. As mentioned, because of the simplified output of SSGs, you can host them anywhere.</p><h2 id="further-reading-on-the-web">Further reading on the web</h2><ul><li><a href="https://www.baseten.co/blog/docs-as-code">How Baseten is using "docs as code" to build best-in-class documentation</a></li><li><a href="https://blog.mia-platform.eu/en/docs-as-code-how-does-it-improve-developer-experience#:~:text=How%20we%20implemented%20Docs%20as%20Code%20within%20Mia%E2%80%91Platform">How we implemented Docs as Code within Mia‑Platform</a></li><li><a href="https://www.docslikecode.com/learn/07-evaluating-ssg-themes/">Evaluating Static Site Generator themes</a></li><li><a href="https://wise4rmgodadmob.medium.com/how-to-create-a-documentation-site-with-docsify-and-github-pages-doc-as-a-code-c419c44e99b7">How to create a documentation site with Docsify and Github Pages</a></li></ul>]]></content:encoded></item><item><title><![CDATA[What is Technical Content Marketing?]]></title><description><![CDATA[Learn about what technical content marketing is, what type of content constitutes technical content marketing, and what it can mean for you as a technical writer.]]></description><link>https://www.everythingtechnicalwriting.com/technical-content-marketing/</link><guid isPermaLink="false">Ghost__Post__628b7ec110c3cd001d59dde2</guid><category><![CDATA[Content Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Mon, 23 May 2022 12:38:54 GMT</pubDate><content:encoded><![CDATA[<p>Last month, I published the <a href="https://www.everythingtechnicalwriting.com/tips-for-freelancing-as-a-technical-writer-and-starting-a-technical-content-marketing-agency/">story of William Imoh and the success of his technical content marketing agency</a> on the #TechContentCreator interview series. Following that, a couple of people reached out to ask what technical content marketing meant.</p><p>In this article, I will try to answer what technical content marketing is, what type of content constitutes technical content marketing, and what it can mean for you as a technical writer.</p><h2 id="what-does-technical-content-marketing-mean">What does technical content marketing mean?</h2><p>To help you understand what technical content marketing is, I'll start by explaining what content marketing is.</p><p>Marcus Sheridan's book "They Ask, You Answer" was my first introduction to the concept of content marketing. He described content marketing as creating SEO-optimized educational content (mostly in the form of blogs, whitepapers, and videos) for a target audience to attract, educate, and hopefully convert them to customers.</p><p>Technical content marketing is simply a flavor of content marketing; it's content marketing for a technical audience. So, following Marcus's definition, technical content marketing can be described as the art of creating educational or problem-solving content for a technical audience (typically software developers, programmers, and engineers) in order to attract them to your site, earn their trust, and hopefully convert them into your customers.</p><p>The goal here is not to sell or promote a product or brand. It's all about producing trustworthy content that addresses topics about a product or niche that the target audience is most likely curious about.</p><p>Done right, content marketing can position a brand as trustworthy and a leader in its field. And <a href="https://business.adobe.com/uk/blog/perspectives/7-in-10-customers-will-buy-more-from-brands-they-trust-uk">studies</a> have shown that brands that earn customer trust are rewarded with more sales, loyalty, and positive recommendations.</p><p>An example of technical content marketing in the wild is the <a href="https://www.containiq.com/blog">ContainIQ blog</a>. ContainIQ is a Kubernetes monitoring tool, so its target audience is software engineers who use Kubernetes or plan to use Kubernetes. Therefore, they focus on creating content on topics of interest to that audience.</p><figure class="kg-card kg-image-card"><img src="https://res-4.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/containiq.png" class="kg-image" alt="" loading="lazy" width="1420" height="787"/></figure><h2 id="the-value-of-technical-content-marketing">The value of technical content marketing</h2><p>The value of technical content marketing is that it facilitates the discoverability of a brand to a larger target audience. A brand is more likely to be noticed by the right audience and associated as a leader in its industry if they create genuinely informative content on topics that matter to their target audience</p><p>Technical writers are commonly hired to write documentation. However, content in the documentation only serves people who are already customers or those who are trying out a product. It doesn't cater to the needs of the broader target audience who are unaware of a product and may need it, or those in the beginning stages of their purchasing journey.</p><p>For example, consider the industry of low code tools. Let's assume that I've seen some Twitter threads and random conversations about the potential of low code tools and how they're excellent for less technical people to build apps fast. Now, I'm curious and would like to use low-code to build out an idea I have.</p><p>The documentation of low code tools like Retool would only contain information on what Retool is and what I need to know to build an app with it. However, I may not even know that Retool is a low-code tool at this stage. I'd be more focused on consuming educational content on everything I need to know to understand the concept of low-code and if it's the right approach for my use case. After that, I'll search for tool options, compare them, and then settle for one which I think is best for me.</p><p>I'll start by googling things like 'what is low code?', 'what are low code tools?', 'low code tools vs. traditional software development, 'should I hire a software developer or build an app with low-code tool?', 'When to use low-code and when not to?', e.t.c.</p><p>After establishing that low-code is right for my use case, I'll then move on to topics like 'best low code tools', 'best low code tools for technical writers', 'low code tools under $10 per month', e.t.c.</p><p>And after I've gotten a potential list of low tools to consider, I'll then embark on comparing my options to help me make my final decision. I'll be searching for comparison guides like 'retool vs. appsmith'.</p><p>In all of these, notice how the type of content found in conventional technical documentation has not come into play? Now, imagine that during my search, I found the kind of trustworthy, high-quality educational content I needed on Retool's site. There is a good chance that I will sign up with them.</p><h2 id="the-role-of-technical-writers-in-technical-content-marketing">The role of technical writers in technical content marketing</h2><p>Many companies have realised the value of the type of content that technical content marketing focuses on. The problem is that some are hiring traditional content marketers to do this job, which may not be very ideal.</p><p>If you're trying to win over a <em>technical</em> audience, you need to communicate with them on a <em>technical</em> level. Software engineers/developers are such a scrutinizing audience that they can easily pick up content written by someone who lacks authentic expertise or experience. With inauthentic traditional-markety type of content, you risk alienating your audience.</p><p>That's why, in my opinion, the best people to create technical content marketing type content are technical writers or developers because they possess that technical authority needed to sound authoritative. Technical writers can handle the broad niche or explanatory product articles. On the other hand, developers can write up rough drafts for more in-depth technical articles and have the technical writers rewrite and clean them up.</p><p>Some companies have now created specialized roles for this type of content under the names of Technical Content Writer, Technical Author, and Developer Writer. In other companies, the technical writer creates both documentation and technical content marketing-type content. Other companies choose to outsource the creation of this type of content to technical content marketing agencies — like William's <a href="https://hackmamba.io/">Hackmamba</a> and <a href="https://draft.dev/">Draft.dev</a>— so they can solely focus on growing their product.</p><p>These technical content marketing agencies act as a link between these companies and experienced technical writers in different niches. In my article on <a href="https://www.everythingtechnicalwriting.com/freelance-technical-writing/">freelance technical writing</a>, I listed some of these technical content marketing agencies that technical writers or developer writers can write for.</p><h2 id="conclusion">Conclusion</h2><p>If you want to learn more about content marketing in general, I recommend reading the book 'They Ask, You Answer'. I learned so much from reading that book. And, if you want to learn more about technical content marketing for startups, <a href="https://draft.dev/learn/101-content-marketing-tips-and-resources">Draft.dev</a> has an excellent hub guide on it.</p><p>Btw, did you notice what's happening? Draft.dev is a technical content marketing agency creating very high-quality educational content to teach startups how to approach technical content marketing. That's content marketing in action. Hope you get it?</p>]]></content:encoded></item><item><title><![CDATA[Technical writer interview: what to expect from personal experience]]></title><description><![CDATA[Read about what a technical writer interview process is like and some of the most common questions you'll most likely be asked.]]></description><link>https://www.everythingtechnicalwriting.com/technical-writer-interview/</link><guid isPermaLink="false">Ghost__Post__628a322ba1aaa0001d351dc6</guid><category><![CDATA[Introductory]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Sun, 22 May 2022 13:31:39 GMT</pubDate><media:content url="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/twinterview.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/twinterview.png" alt="Technical writer interview: what to expect from personal experience"/><p>I've been interviewing for technical writing/documentation roles partly to improve my interviewing skills and see what opportunities are out there. </p><p>In this article, I talk about what most technical writer interview processes are like and some of the most common questions I've been asked during these interviews.</p><p><strong>Note</strong>: What you're about to read is based on my personal experience and may not totally apply to your own scenario. Regardless, I still believe that the information contained in this article will prove helpful to you if you're interviewing for a technical writing role.</p><h2 id="summary-of-a-typical-technical-writer-interview-process">Summary of a typical technical writer interview process</h2><p>The interview process begins either when a recruiter contacts you or when you send in your resume and/or cover letter. If the recruiter thinks you're a good fit, they'll usually invite you to a 30 mins introductory/informational chat to get to know you better, tell you more about the company, and understand your background and your expectations for the role. They'll also ask questions about the experiences listed on your resume, as well as questions to determine if you're a good culture fit.</p><p>After the chat, the recruiter will most likely ask you to send your technical writing samples or your technical writing portfolio. Sometimes you may be asked to submit your samples alongside your resume ( I have a very detailed article on <a href="https://www.everythingtechnicalwriting.com/technical-writing-portfolio/">how to create a tech writing portfolio</a>). At this stage, endeavor to submit writing samples that tally with the kind of document the role requires.</p><p>If the recruiter feels like you might be a good fit, they'll forward your resume and writing samples to the hiring manager (who will most likely be the team lead). If the hiring manager likes what they see, you'll be invited for a more technical interview with them.</p><p>During this technical interview, the hiring manager will most likely ask questions about your writing process and your knowledge of technical writing. Sometimes, you may be given a take-home assignment after the technical interview (or even during the introductory call phase),.</p><p>Most of my take-home assignments have been on structure and information architecture. This might be because I've been applying for mid-level technical writer roles. Three of the companies I interviewed with asked me to look at a piece of documentation and propose better structural solutions. One of them phrased the task like so: "I'd like to ask you to either look at the documentation as a whole or pick one specific page and list things that you <strong>don't</strong> like about it, how you would change it, and why (to improve readability, UX, aesthetics, etc.)." Here's one of my <a href="https://docs.google.com/document/d/1z5gy4wqq-ihLMDi2wlRGl0mACeaVsau8rEb0rFEy1mU/edit?usp=sharing">sample solutions</a> for such a task.</p><p>After reviewing your take-home assignment (if any) and your performance, if the hiring manager feels like your skill set matches the experience they're looking for, you'll be invited to a final interview with the rest of the team you'll most likely be working with. Questions you'll be asked will usually be team culture-fit questions.</p><p>During this whole interview process, you'll always be given a chance to ask your own questions. Never say you do not have any questions. Your interviewer could sometimes interpret such response to mean that you've not done your research about the company or you're just uninterested. Always have your own questions to ask.</p><p>Now that I've summarized the entire process let's get into some of the common questions I was asked and some questions you can ask too.</p><h2 id="common-technical-writer-interview-questions">Common technical writer interview questions</h2><h3 id="q-have-you-had-the-chance-to-take-a-look-at-our-documentation-what-did-you-like-about-it-and-what-do-you-think-can-be-improved">Q: Have you had the chance to take a look at our documentation? What did you like about it, and what do you think can be improved? </h3><p>Before any interview, always take the time to go through their documentation or whatever section of content you'll be working on. Make a list of things you liked and why you like them, and also a list of things you think can be improved on and why. This can be as little as a typo, making a header shorter, or adding more whitespace to the layout. </p><p>Check <a href="https://docsbydesign.com/2021/10/09/what-do-you-think-of-our-docs/">this Bob Watson's article</a> for more tips on how to answer this question.</p><h3 id="q-why-did-you-choose-to-become-a-technical-writer">Q: Why did you choose to become a technical writer? </h3><p>My answer to this question is personal and probably wouldn't be the same as yours. Talk about your motivations and what you enjoy the most about tech writing.</p><h3 id="q-assume-the-engineering-team-just-completed-work-on-a-feature-and-youre-expected-to-document-it-how-would-you-go-about-that">Q: Assume the engineering team just completed work on a feature, and you're expected to document it. How would you go about that? </h3><p>My answer to this question is that I would first try out the feature myself using whatever readme that the engineering team had already prepared. I'll note any frictions or difficulties I run into, so I ask questions about them later on. </p><p>After that, I would request a 30-minute or an hour chat with the engineers who built the feature so that I can learn more about the feature and clarify my questions. </p><p>When I feel like I have learned enough about the feature, I will consult my notes to come up with an outline based on the type of doc we're looking to create. After that, I'd discuss the outline with my manager and other key members. Once we come to an agreement, I'd write the first draft.</p><h3 id="q-what-would-you-say-is-the-most-important-skill-for-a-technical-writer-to-have">Q: What would you say is the most important skill for a technical writer to have? </h3><p>I always answer that the most important skill for a technical writer to have is empathy and making an effort to understand who the users of the documentation are. Because at the end of the day, we're not creating documentation for ourselves. We're creating it to help users, and you can't create something helpful for a particular audience if you do not take the time to understand them and their pain points.</p><h3 id="q-how-do-you-perceive-and-handle-feedback">Q: How do you perceive and handle feedback? </h3><p>My answer to this question is that getting negative or critique feedback hurts, but I've learnt to disassociate any feedback I get as a reflection of my ability as a writer. Instead, I've learned to accept and even appreciate feedback because input from editors and others is how I've been able to hone my craft and become a better writer. Regardless, I also know when to ignore some sort of feedback and follow my gut.</p><h3 id="q-can-you-give-an-example-of-a-time-you-collaborated-with-people-to-create-a-doc">Q: Can you give an example of a time you collaborated with people to create a doc?</h3><p> The instances I provide as answers to this question are personal and are about different projects I've had the opportunity to work on. Simply think of a time you worked with someone else to create a document. This person could be an editor, a technical reviewer, or what have you.</p><h3 id="q-how-do-you-handle-conflict-between-you-and-other-team-members-for-example-lets-assume-you-believe-that-task-x-should-be-done-in-a-particular-way-but-most-of-your-team-members-think-it-should-be-done-a-different-way-what-would-you-do-in-such-scenarios">Q: How do you handle conflict between you and other team members? For example, let's assume you believe that task x should be done in a particular way, but most of your team members think it should be done a different way. What would you do in such scenarios? </h3><p>My answer to this question is that I focus on the collective goal instead of what I believe is right. I would share my thought, but I would still be open to hearing what others have to say. And if the majority votes for a particular approach, I'd be willing to execute it because I know there are no definite rules in tech writing. It's an iterative and experimental process, and the only thing that matters is serving users' needs.</p><h3 id="q-whats-one-failuredisappointment-youve-recently-experienced-inside-or-outside-work-and-how-did-you-handle-it">Q: What's one failure/disappointment you've recently experienced inside or outside work, and how did you handle it? </h3><p>Interviewers ask this question to see how you handle failures, mistakes, or disappointments. This is because, in most organisations (especially startups or teams at their early stages), nothing is set in stone; projects can be discontinued out of the blue.</p><p>They want to know if you're the kind of person who would just sulk over a disappointment or one who would pick up the lessons and move on? Tell a story about a time you made a mistake and were able to apply the lessons from that event to future uses.</p><h3 id="q-what-metrics-do-you-think-should-be-tracked-across-documentation">Q: What metrics do you think should be tracked across documentation? </h3><p>I'd say some of the most important metrics to track in documentation are:</p><ul><li>Clicks and impressions: This will help understand what kind of info users are looking for when they land on a particular doc page. By doing this, we may be able to improve the discoverability and findability of content, as well as provide better answers.</li><li>Pageviews: This helps understand what doc pages should be considered a priority because of the number of page views and session duration.</li><li>User flow or journey: This will help us understand the entire journey of the readers and the kind of information they're looking for.</li></ul><p>In my opinion, regardless of these metrics, nothing beats making provision for direct feedback in doc pages or asking your users about your docs to get a sense of if it's fulfilling its purpose.</p><h3 id="q-whats-a-writing-project-you-worked-on-recently-that-youre-proud-of">Q: What's a writing project you worked on recently that you're proud of? </h3><p>Think about a writing project that was seemingly difficult but which you later delivered on. Talk about the challenges you faced, how you overcame them and what you learned from the entire process.</p><h2 id="questions-you-can-ask">Questions you can ask</h2><p>As I previously mentioned, when your interviewers ask you if you have any questions for them, do not say no. Not only does it put you off as uninterested, but it also robs you of the opportunity to spot any red flags in the company's culture and truly determine if the role and company are right for you.</p><p>Here are some of the questions that I usually ask, alongside some recommended by my friends.</p><ul><li><strong>What are the KPIs for this role? And what does success look like in this role?</strong></li><li><strong>How does the company support the technical writing team to enable them to do their best work?</strong> If you sense that a company does not have systems that show that they clearly value the work that technical writers do, run. It can get very frustrating trying to convince management of the value of your work or existence.</li><li><strong>What's your favorite thing about working here, and if given the opportunity, what's one thing you'd want to change?</strong></li><li><strong>What are some exciting projects that the team or the company is currently focused on?</strong></li><li><strong>What's the revenue model of the company? </strong>This is especially important for startups to help you guage their level of stability.</li><li><strong>How does the company encourage team bonding both within and between teams?</strong></li><li><strong>Can you tell me about a time that you made a mistake and how your team and leadership responded?</strong></li><li><strong>In what ways does the team or company encourage, support, and plan for the growth of their employees?</strong></li><li><strong>How did this position become available?</strong></li></ul><p>While asking these questions, pay good attention to the answers you get. They'll help you really understand the company's culture. Listen to your instincts and how comfortable you feel. If something is not right, then it's not right. Better to turn down a job than to join a toxic organisation.</p><h2 id="conclusion">Conclusion</h2><p>I hope these few tips help you with your upcoming interviews. If you do get the job, congratulations!!</p><p>If you don't, don't fret. Ask for feedback and apply that feedback to your next application and see it as an opportunity to get more interviewing experience. Read their documentation, blog articles, social media field, and anything that can help you build a better understanding of the company, product, and its users. You don't want to walk into an interview unprepared.</p><p>If you have questions or anything you'd like me to add to this article based on your own experience, please reach out to me on <a href="https://twitter.com/_MsLinda">Twitter</a>.</p>]]></content:encoded></item><item><title><![CDATA[TCSS #5: What does a technical writer at Google do + Interview process]]></title><description><![CDATA[Read about what it takes to become a technical writer at Google, as told by a technical writer at Google.]]></description><link>https://www.everythingtechnicalwriting.com/what-a-technical-writer-at-google-does/</link><guid isPermaLink="false">Ghost__Post__628744ee6e444f001d821479</guid><category><![CDATA[Interviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Fri, 20 May 2022 15:51:51 GMT</pubDate><media:content url="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/techcontentseries-5.png" medium="image"/><content:encoded><![CDATA[<h1/><img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/techcontentseries-5.png" alt="TCSS #5: What does a technical writer at Google do + Interview process"/><p><em>The Tech Content Creator Series is a monthly interview series in which I chat with people in technical content creation roles (technical writers, documentation engineers, developer advocates, and what have you) about their careers. My hope is for their stories to impact, inspire, and motivate you.</em></p><p>For this month, my guest was Alexandra White. Alexandra is a technical writer for Google Chrome, where she writes documentation for Privacy Sandbox. She also co-chairs the documentation accessibility working group and has given several talks on documentation.</p><p>In this episode, we chat about her journey into technical writing, what she does as a technical writer at Google, and the interview process for a technical writing role at Google. Enjoy!</p><h2 id="me-how-did-you-get-into-technical-writing">Me: How did you get into technical writing?</h2><p><strong>Alexandra</strong>: I got into technical writing through a series of connected choices. I studied professional writing at Michigan State University, where one could either focus on book publishing, non-profit grant writing, or digital and technical writing. I chose digital and technical writing.</p><p>However, most of my technical writing classes were so boring that I wondered why anyone would ever want to be a technical writer. As a result, I decided I would become a social media marketer when I left school; I would write tweets for a living, and it would be fun. I applied to over 60 jobs before I finally got one. Quickly after I started a social media role, I realized that it bored me to death.</p><p>While I was at university, I was also taught how to code and build WordPress themes. So one day, I asked my boss if it was okay if I built our websites, in addition to handling social media. He gave me the go-ahead. I discovered I enjoyed building websites much more than writing social content, so as a result, I decided to pursue web development full-time.</p><p>I found a new job as a web developer, where we were tasked with maintaining websites built as far back as 1998 as well as modern websites, and we had no documentation of any kind. Whenever I had to fix an old website, I would consult the person who built it to find out where specific files were, what I needed to know to ensure that the website wouldn't break, and whether it had any dependencies. This process was really frustrating, so I launched a technical blog to convince my colleagues to write docs.</p><p>I applied for a scholarship to attend <a href="https://conferences.oreilly.com/velocity/vl-ny.html">O’Reilly’s Velocity conference</a>, where I did my best to network. I met an engineer, to whom I lamented about my documentation frustrations. I told him about the blog and my mission to get better documentation. In response, he asked me if iI would consider writing documentation full-time.</p><p>I thought back to my boring college classes, and really considered what it would mean to leave engineering. Ultimately, he and my soon-to-be boss convinced me it was a worthwhile challenge. I applied for and accepted the job as <a href="https://www.joyent.com/blog/dockerizing-a-simple-app">Joyent’s Documentation Editor</a>. I knew almost nothing about cloud services and back-end development when I started.Knowing nothing was very beneficial for that job because I could ask what some may have considered 'stupid' questions, which helped me translate very technical engineering language into human-friendly language.</p><h2 id="me-how-did-you-land-this-job-at-the-cloud-company">Me: How did you land this job at the cloud company?</h2><p><strong>Alexandra</strong>:  It turned out the person I was talking to at that conference worked at Joyent and his team recently decided they would hire a technical writer. He connected me with the hiring manager, I submitted an application, got interviewed, and landed the job.</p><p>As a reminder, networking, reaching out to people, going to places where people are, and talking about yourself can create opportunities. This is especially hard in the pandemic, but I strongly recommend seeking out conferences and scholarships if needed. You never know what opportunities could come from the people you meet.</p><h2 id="me-you-work-at-google-now-what-department-do-you-work-in-and-what-are-your-responsibilities">Me: You work at Google now. What department do you work in, and what are your responsibilities?</h2><p><strong>Alexandra</strong>: When I joined Google in December 2018, I started out as a technical writer for the <a href="https://support.google.com/admanager/">Google Ad Manager Help Center</a>. Google Ad Manager is a corporate enterprise product that helps publishers such as news websites, retailers, etc., monetize their websites. My role was to write user-facing documentation to help our users learn about ad bidding and delivery.</p><p>I did that for over two and a half years before seeking other internal opportunities. The great thing about Google is that there are actually dozens of exciting small projects or big projects inside one gigantic corporation.</p><p>In October 2021, I switched positions at Google. Now, I work for <a href="https://developer.chrome.com/">Google Chrome</a> on the developer relations team. Here, my job is to write documentation for the <a href="https://privacysandbox.com/intl/en_us/open-web/">Privacy Sandbox</a>. The Privacy Sandbox is a series of proposals to</p><p>protect people's privacy online, while giving companies and developers tools to build thriving digital businesses.</p><h2 id="me-what-was-the-interview-process-for-google-like-and-what-are-some-things-you-did-to-stand-out-if-any">Me: What was the interview process for Google like? And what are some things you did to stand out (if any)?</h2><p><strong>Alexandra</strong>: I honestly never thought I'd work at Google. I thought that my education wasn't good enough and that since my job experience was mostly at small companies, Google wouldn't care. However, since joining, I've met so many other people who felt the same way.</p><p>I initially applied for a developer advocate job because I missed (and still miss) web development. I believe the recruiter for that position gave my resume to a technical writer recruiter because of my experience at Joyent. The technical writer recruiter contacted me to ask if I would consider a technical writing position instead.</p><p>I had a phone interview with the recruiter, who then asked for me to submit writing samples. Then, a committee reviewed my writing samples and thought I had the needed skill set. Following that, I was invited to a series of interviews to put my technical writing skills to the test.</p><p>I was interviewed by 5 Google employees; 3 technical writers, 1 technical writing manager, and 1 engineer. I was asked about my writing process, best practices, and about my various employment experiences listed on my resume. Then the engineer asked me to write some code on a whiteboard to build something and explain the code.</p><p>Other technical writers at Google have told me that’s uncommon for this interview process. I assume the engineer asked because my resume mentioned that I knew how to write code. As technical writers, our job is not to write the code, but to explain it. </p><p>After all the interviews, I was told they'll get back to me in a week. In total, the process took 13 months: I applied in November 2017 and joined in December 2018.</p><h2 id="me-why-did-the-interview-process-take-so-long-is-that-duration-standard">Me: Why did the interview process take so long? Is that duration standard?</h2><p><strong>Alexandra</strong>: No. My situation was a rare occurrence. The average interview process here is two to three months, and they are trying to speed it up even more.</p><p>At Google, after an interview, performance notes are sent to a hiring committee, which decides whether or not to hire. If the committee decides to hire someone, they also determine what level to hire the person at based on their experience. By the time the committee made an affirmative decision on my application, the job opening I had applied for had been filled. The good thing is, when interviewing at Google, you're not necessarily being interviewed for one specific position but for a broad position type. I was being interviewed for technical writer roles.</p><p>So, seeing that the specific role I applied for had been filled, the recruiter reached out to me to make me an offer for a different position. I was so delighted that I was considered good enough, but the position was offered at a salary which was lower than my salary at Joyent. I told the recruiter that I really wanted to work with them, but they needed to meet my salary expectations. Also, the role required me to move to California, but I didn't want to move away from New York. The recruiter told me they'll think about it and also keep me in mind for future opportunities. One thing about Google is that if they think you are good enough, they will do whatever it takes to make things work.</p><p>In September of 2018, while I was interviewing for other positions, the recruiters returned, asking if I was interested in another opportunity. I was asked to submit one more writing sample and interview with a new hiring manager.</p><p>For my writing sample, I did something which I would encourage every applicant to do. I took a blog post that I wrote a few years ago and applied a style guide to it. I submitted the old blog post (without the style guide application) and the new one (with the style guide applied). I also submitted a document detailing all the changes I made and why those changes were necessary.</p><p>As I was told by my to-be manager, that singular submission was what sold me to them and moved my level up so that I could be paid the salary that I asked for. They were so excited to see that I could follow a style guide and could explain why it mattered.</p><h2 id="me-were-you-specifically-asked-to-submit-a-style-guide-formatted-blog-post">Me: Were you specifically asked to submit a style-guide formatted blog post?</h2><p><strong>Alexandra</strong>: No, that was entirely my idea. I wanted to impress them. I was asked to submit whatever I thought was my best piece of writing.</p><p>Alongside the style guide documents, I also submitted other docs because I knew it was important to present different kinds of writing. I submitted one API reference doc, a technical blog post, and video documentation.</p><h2 id="me-based-on-your-application-experience-what-tips-can-you-give-prospective-applicants">Me: Based on your application experience, what tips can you give prospective applicants?</h2><p><strong>Alexandra</strong>: My first tip would be to use the exact verbs used in the job posting on your resume. The second tip is to use as many metrics as possible on your resume because recruiters want to see how you made a difference in your previous roles. And the third tip would be to curate a solid technical writing portfolio.</p><p>Also, somebody recently asked me what to do if they want to be a technical writer but don't have any writing samples. My answer is to create documentation for an open-source project. Go to GitHub, look at projects, and see if you can write documentation for any. Another way is to write sample documentation for very popular products. For example, you could write instructions for setting up filters in Gmail.</p><p>It’s important to note, this is advice based on personal experience. However, <strong>I am not speaking as a representative of Google</strong>. Following my advice is not a guarantee for an interview or a job at Google.</p><h2 id="me-still-on-google-do-you-think-your-writing-degree-gave-you-an-edge-does-google-place-priority-on-writing-degrees-for-technical-writing-roles">Me: Still on Google. Do you think your writing degree gave you an edge? Does Google place priority on writing degrees for technical writing roles?</h2><p><strong>Alexandra</strong>: They encourage people to have a writing-related degree. That said, while I was on the Ad Manager team, three of seven writers had degrees in technical or professional writing, and the other four didn't.</p><p>One person had a Literature in English degree, another person had a computer science degree, and the others had journalism degrees. If you don't have a writing degree, there are a number of certifications out there that you can take. </p><p>Google has created some <a href="https://developers.google.com/tech-writing">technical writing courses</a>. However, like my other advice on writing samples, this doesn’t constitute a job guarantee. I think they’re awesome resources but they are not the same as other formal education.</p><h2 id="me-i-found-you-through-one-of-your-talks-which-you-delivered-excellently-so-for-people-who-want-to-give-talks-do-you-have-any-tips-for-speaking-at-conferences-and-finding-conferences-to-speak-at">Me: I found you through one of your talks which you delivered excellently. So, for people who want to give talks, do you have any tips for speaking at conferences and finding conferences to speak at?</h2><p><strong>Alexandra</strong>: Years ago, I decided that I wanted to travel the world and have somebody else pay for it. I found that the best way to do that is to speak at conferences. I always look for conferences that pay for flights and hotels.</p><p>I found the Write The Docs conference by searching for technical writing conferences. I saw that there was one happening in Portland, Oregon, so I asked for permission from my company to attend.</p><p>The first talk was given by a woman named <a href="https://www.youtube.com/watch?v=_HCmFvxxKaQ">Kat King</a>, who was a developer education manager at Twillo. The talk was so inspiring to me. I told myself I wanted to be able to make other writers feel the way she made me feel — like I could be better.</p><p>I decided that I would apply to speak at the next Write The Docs conference, which was going to be in Prague. I started thinking to myself, what am I working on that people would find valuable? That's how I came up with <a href="https://www.youtube.com/watch?v=u119GkGSYII">the talk on tearing down your documentation</a>.</p><p>When creating a conference talk, the most important thing to focus on is what people will walk away with and how they can accomplish a goal. Don't just say “here are five things you need to do”; tell how you did it and walk them through the process.</p><p>To find calls for papers requests, there are a bunch of different websites I use: <a href="https://twitter.com/callbackwomen">CallbackWomen</a> on Twitter, <a href="https://www.cfpland.com/">CFP land</a>, e.t.c.</p><p>A low-pressure way to get used to giving talks is to start with local meetups and virtual talks.</p><h2 id="me-for-your-talk-on-tearing-down-documentation-i-noticed-you-had-little-note-cards-that-you-read-from-nice-strategy">Me: For your talk on tearing down documentation, I noticed you had little note cards that you read from. Nice Strategy.</h2><p><strong>Alexandra</strong>: Yes, and I think more people should do that. That was the first talk I gave. I wrote all of my notes on note cards because I couldn't memorize my entire talk. Although I started my higher education in the theater school, I have never been good at memorizing.</p><p>Since then, I haven't used note cards, but I write everything on my speaker notes and sometimes read it word-for-word. Some people can just write bullet points in their speaker notes and talk extemporaneously. I can't do that, so I use my notes to keep me on track.</p><p>There, I just told you my secret, and now everyone will know too :)</p><h2 id="me-do-you-have-any-final-words-of-advice-for-anyone-trying-to-get-into-technical-writing">Me: Do you have any final words of advice for anyone trying to get into technical writing?</h2><p><strong>Alexandra</strong>: I'd say anyone can be a technical writer. Interestingly, there's a lot of focus on STEM, but writing is actually the foundation of every career.</p><p>In addition, you should know it takes practice to get good at it. Everyone can do it if they take the time to practice writing and consult style guides. Every day I look at other writers' documentation and think, "Wow, that was such a succinct way of writing that".</p><h2 id="me-do-you-have-any-style-guides-you-would-recommend">Me: Do you have any style guides you would recommend?</h2><p><strong>Alexandra</strong>: I have to mention the <a href="https://developers.google.com/style">Google developer documentation style guide</a>. It's a constantly evolving document. Also, I think the <a href="https://www.chicagomanualofstyle.org/home.html">Chicago Manual of Style</a> is what most of the writers on my team refer to when not looking at our developer style guide.</p><h2 id="me-last-question-tell-me-a-fun-fact-about-you-unrelated-to-work-or-your-career">Me: Last question, tell me a fun fact about you unrelated to work or your career.</h2><p><strong>Alexandra</strong>: I started my education studying theatre (P.S I love theatre). And, when I got to New York, I made friends with people who ran a small theatre company called <a href="http://www.thedirtyblondes.org/">The Dirty Blondes</a>. They asked me if I would be a stage manager. So after my work hours, I would then go to rehearsal.</p><p>The <a href="http://www.thedirtyblondes.org/the-american-play.html">last show I worked on</a> was performed at the New York International Fringe Festival. It was a 45-minute one-act play, and we were selected among 10 other shows to go on Broadway. It was so cool.</p><hr><p><em>That's all from Alexandra. If you'd like to connect with Alexandra, reach out to her on <a href="https://twitter.com/heyawhite">Twitter</a>, and check out some of her <a href="https://heyawhite.com/speaking/">talks</a>.</em></p><p><em>You can also read other episodes of The Tech Content Creator series <a href="https://www.everythingtechnicalwriting.com/tag/interviews/">here</a>.</em></p></hr>]]></content:encoded></item><item><title><![CDATA[TCCS #4: Tips for freelancing as a technical writer and starting a technical content marketing agency with William.]]></title><description><![CDATA[> The Tech Content Creator Series is a monthly interview series in which I
interview people in technical content creation roles (i.e. technical writers,
documentation engineers, developer advocates, and what have you) about their
careers. My hope is for their stories to inspire, motivate, and hopefully impact
you.

William Imoh (popularly known as iChuloo) is currently a Technical Product
Manager at PotterBuddy. Notwithstanding, his career was built on the foundations
of Technical writing. Willi]]></description><link>https://www.everythingtechnicalwriting.com/tips-for-freelancing-as-a-technical-writer-and-starting-a-technical-content-marketing-agency/</link><guid isPermaLink="false">Ghost__Post__62515c62e46403001d4450e2</guid><category><![CDATA[Interviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Sun, 10 Apr 2022 08:29:57 GMT</pubDate><media:content url="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/techcontentseries1.png" medium="image"/><content:encoded><![CDATA[<blockquote><em>T<em>he Tech Content Creator Series is a monthly interview series in which I interview people in technical content creation roles (i.e. technical writers, documentation engineers, developer advocates, and what have you) about their careers. My hope is for their stories to inspire, motivate, and hopefully impact you.</em></em><br/></blockquote><img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/techcontentseries1.png" alt="TCCS #4: Tips for freelancing as a technical writer and starting a technical content marketing agency with William."/><p>William Imoh (popularly known as iChuloo) is currently a Technical Product Manager at PotterBuddy. Notwithstanding, his career was built on the foundations of Technical writing. William is also the founder of Hackmamba, a young technical content marketing agency that just crossed $10K in author payouts.</p><figure class="kg-card kg-embed-card"><blockquote class="twitter-tweet"><p lang="en" dir="ltr">Crossed $10k in author payouts at <a href="https://twitter.com/hackmamba?ref_src=twsrc%5Etfw">@hackmamba</a> 🙏🏽✍🏼</p>&mdash; William (@iChuloo) <a href="https://twitter.com/iChuloo/status/1503448844834676749?ref_src=twsrc%5Etfw">March 14, 2022</a></blockquote>
<script async="" src="https://platform.twitter.com/widgets.js" charset="utf-8"/>
</figure><p>In this episode, he talked about how the act of volunteering and technical writing gave him a start in his career. He also shared about how he runs his young technical content marketing agency, as well as some valuable advice for freelance technical writers or anyone looking to tow the same path.</p><p>Enjoy!</p><hr><h3 id="linda-welcome-william-so-i-researched-you-and-found-out-that-youve-been-a-bit-of-everything-product-manager-software-engineer-developer-advocate-%E2%80%A6">Linda: Welcome, William. So, I researched you and found out that you've been a bit of everything: product manager, software engineer, developer advocate …</h3><p><strong>William:</strong> Yea. I do everything except design.</p><h3 id="linda-interesting-tell-me-how-you-got-into-tech-your-journey-up-until-now">Linda: Interesting. Tell me how you got into tech; your journey up until now.</h3><p><strong>William</strong>: I studied chemical engineering at the university. During the mandatory Nigerian NYSC one-year service, I figured that if I wanted to build all the ideas I had, I needed to learn how to code. </p><p>After service, I quit a job that was supposed to pay me about 120k in Abuja because I knew that wasn't what I wanted. I relocated to Lagos and started learning how to code. I wrote my first lines of code in April 2017.</p><h3 id="linda-were-you-learning-how-to-code-yourself-or-was-it-with-a-supervised-program">Linda: Were you learning how to code yourself, or was it with a supervised program?</h3><p><strong>William</strong>: Nah, I learned on my own using Freecodecamp and CodeCademy. Then I started writing about what I was learning on medium: React, static site generators, e.t.c. I also started travelling around Nigeria on my own budget to talk about these things.</p><h3 id="linda-you-were-being-invited-to-conferences-to-give-talks">Linda: You were being invited to conferences to give talks?</h3><p><strong>William:</strong> Yeah. And, if you don't invite me, I will invite myself. There were times I travelled to Kenya, Uganda, etc., to talk at meet-ups there. </p><h3 id="linda-did-you-have-a-full-time-job-while-doing-all-these">Linda: Did you have a full-time job while doing all these?</h3><p><strong>William:</strong>  No</p><h3 id="linda-so-how-were-you-making-money-then">Linda: So, how were you making money then?</h3><p><strong>William: </strong>I had saved 200k from when I was in Abuja and was supposed to pay myself 30K for like 6 months till I got an internship at HNG — that was my plan. </p><p>But, I went faster than that. I started writing articles for <a href="http://scotch.io">scotch.io</a>, and I was paid 30k per article. </p><p>After a while, because of my relationship with Chris (the creator of scotch.io), I got a more committed gig as like a developer advocate. This paid about $400. I was writing articles, reviewing articles from other writers, managing the developer newsletter, and doing a bit of developer marketing.</p><p>I was also volunteering at <a href="https://forloop.africa/">Forloop Africa</a>. I would volunteer to host meet-ups in different places. Ridwan (one of the founders of Forloop) would give me money to host the meet-up and some extra for transportation.</p><p>Volunteering played a significant role in my life. I would volunteer for anything knowing that I would not be paid. Volunteering has the effect of making others feel as if they owe you. And if you're building up your career, you need stuff like that. That's how you get influential people to notice you.</p><p>In 2018, I decided I was going to get a full-time job. So, I joined Andela. </p><h3 id="linda-what-was-your-job-title">Linda: What was your job title?</h3><p>William: It was Talent Partnership Associate.</p><h3 id="linda-what-did-the-job-entail">Linda: What did the job entail?</h3><p><strong>William</strong>: It was to manage the <a href="https://andela.com/learning-community/">Andela Learning Community(ALC)</a>. I was paid about 150 thousand naira. I took the job because I just wanted to work structured organization, which was something I'd never had. </p><p>I kept travelling, and everywhere I went, I'd find meet-ups and give talks. In 2019, I travelled to the US. One of the benefits of my Andela job was a US visa, so I decided to make use of it. While there, I did like a tech tour thing. I spoke about jamstack and African tech communities at several meet-ups. All of this earned me some social capital and credibility, which proved useful later.</p><p>After the tech tour, I came back to Nigeria and decided that I would quit my job at Andela. I left without having another job.</p><h3 id="linda-hmmm-what-did-you-do-after-that">Linda: Hmmm. What did you do after that?</h3><p><strong>William</strong>: I started doing random stuff; I took a side gig to build a website for someone in France, did some open-source maintenance for Gatsby, and wrote more articles for scotch.io. I was paid $200 per post, and I was content with it because it was enough for me to get by.</p><p>After a while, I decided that I would find something else to do. But first, I wanted to visit Dubai.</p><p>So, a couple of friends and I went to Dubai. I met a number of people who were already familiar with me due to all the travelling and talking I'd done. One of them was Meabed, an Egyptian who would later become my manager.</p><p>When I returned to Nigeria, I started <a href="https://dentry.io/">Dentry</a>. </p><h3 id="linda-what-is-dentry">Linda: What is Dentry?</h3><p><strong>William:</strong> Dentry is a job board for beginner techies. Many beginners find it hard to get jobs. Still, there are opportunities like internships, boot camps, free programs, and entry-level jobs. I decided to build a simple job board in one weekend and just post entry-level opportunities that I come across there. Now, I've employed someone else to work on it. Basically, the person searches for entry-level jobs and puts them on Dentry.  </p><p>While working on Dentry, Chris called me to ask if I remembered Meabed from Dubai. He said Mebech needed a technical product manager to lead a team of engineers to build an online grocery platform and asked if I was interested. I told him that I am not a product manager, but I've done many things, and product management shouldn't be the most difficult. </p><h3 id="linda-so-how-did-you-convince-them-to-hire-you-as-a-product-manager-then">Linda: So how did you convince them to hire you as a product manager then?</h3><p><strong>William:</strong> I called Mustapha Garuba, who used to be a product manager at Andela, and asked him to tell me everything about product management and what he does on a daily basis. I also read a book called "Escape the Build Trap" by Melissa Perri, watched a YouTube video on product management, and that was it. I became a product manager. **laughs**</p><p>I had my interview with Mebech. He explained the idea, then asked for my opinion, and I sold him the future of groceries. And the rest was history. </p><p>The job required that I relocate to Dubai. At first, I wasn't sure. You see, I wanted to build the future of tech in Africa. But, I was going through this breakup at that time, so I finally decided to leave the country and get a fresh start. </p><h3 id="linda-ive-heard-that-breakups-can-propel-people-to-greatness">Linda: I've heard that breakups can propel people to greatness</h3><p><strong>William:</strong> Yeah. I moved to Dubai with two friends, John and Emmanuel, who I hired as software engineers. We worked for like 16-18 hours a day because we were building a startup from scratch, and we did it for months until the pandemic came in 2020. </p><p>Sometime during the pandemic, the company folded, and I decided to get a job and move to Norway. The thing nobody prepares you for with applications is the rejections. I was applying to almost 30 jobs every day and was getting rejected left, right and center. </p><p>Finally, after applying to about 250 jobs, I got an interview. They wanted a technical product manager that would be in charge of partner integrations. I looked at the job description, and it matched with everything I did. I was going to be helping build plugins, handle documentation, and speaking to external stakeholders. </p><p>I started the job in April 2021, and was working remotely from Dubai. By the way, I feel everyone should work with European companies once in their lifetime because things are so chill. Your dog can be sick, and you'll be allowed to take the day off. As soon as travel restrictions was lifted, I packed my bags, sold my things, and took a one-way ticket to Oslo.</p><h3 id="linda-so-when-did-hackmamba-come-into-the-picture">Linda: So when did Hackmamba come into the picture?</h3><p><strong>William: </strong>It was during the time that the startup folded. I was writing a lot of technical articles. I noticed that there were a lot of companies that needed technical writers but couldn't find many at the level of writing expertise they required. I started <a href="https://hackmamba.io/">Hackmamaba</a> to fill that gap. </p><p>At Hackmamba, we see technical content as a product — that's our mantra. We focus on the users and also the business. People often write content for the users, and they do not think about the business. But it is the business that pays for the content. Therefore, there should be a business objective to every content. It could be marketing, or they want to offset a feature or something else.</p><p>Our first clients were Cloudinary. I was already consulting for them, so I told them to now see me as a company they would be contracting. </p><p>Our promise to our clients is that any content that comes through us will be of the best quality. We have four steps of review: peer reviews, internal reviews, external reviews, and then there's me, the final boss whose job is to tear down the article. We also make use of Grammarly premium. That way, we consistently create great content, and the authors get to learn a lot.</p><p>At Hackmamba, we're a community of people with shared interests. My goal is for everybody to leave better than they came. We're not just about creating content for our clients; we also share opportunities with our writers. We have a channel where we share developer advocate jobs, technical writing jobs, e.t.c. I spend time reviewing the content they use to apply to these jobs, providing advice on negotiating salaries, and giving them hacks to update their LinkedIn profile. </p><p>So I have been running Hackmamba, working full-time as a product manager, building a startup with my friend Chike, and running Dentry as well.</p><h3 id="linda-as-a-contracting-organization-how-do-you-recruit-clients-and-convince-organizations-that-what-you-have-to-offer-them-is-valuable">Linda: As a contracting organization, how do you recruit clients and convince organizations that what you have to offer them is valuable?</h3><p><strong>William: </strong>I have like a shortlist from LinkedIn where I find potential companies. I use the strategy I've always used: I reach out and offer to do something for free. I would do it really well so that they'll see the value, then I'll charge for the next thing.</p><h3 id="linda-how-do-you-hire-and-vet-technical-writers-for-hackmamba">Linda: How do you hire and vet technical writers for Hackmamba?</h3><p><strong>William:</strong> I periodically put out a form for people who want to join Hackmamba as an author. My requirements are that they have at least two years of technical experience and samples of content they've written to ensure that they can write. I know they won't be the best technical writers out there. But they learn and become better from peer-review sessions from myself and others. </p><h3 id="linda-what-hacks-or-advice-would-you-give-to-tech-writers-who-want-to-build-their-careers-around-freelancing">Linda: What hacks or advice would you give to tech writers who want to build their careers around freelancing?</h3><p><strong>William:</strong>  I would say someone starting out should learn to sell. Find a book on sales, read it. Also, learn to make friends with people you want to work with, and offer to help them. This could be with the developer advocates, the content marketer, or what have you.</p><h3 id="linda-what-do-you-mean-become-friends-with-them">Linda: What do you mean, become friends with them?</h3><p><strong>William:</strong> I mean find them (although it sounds creepy), do free stuff for them, and share it with them. Everyone likes free stuff, and it's an opportunity to show what you can offer… like snippets. </p><p>So for me, I tell the content marketer I want to work with that I can help them amplify whatever they create using my Twitter platform, where I have quite some reputation and social capital. I also tell them that they can send anything they make my way, and I'll help them review it.</p><p>I sometimes write articles for companies that I want to work with without paying me. Most times, they do not even know who I am. My job with that free article is to encourage some sort of business metric like conversion or sign-ups. So I'll write the article and then add UTM parameters with Hackmamaba as the UTM source. </p><p>That way, the analytic software used by that company will capture that parameter anytime anyone clicks that link. You get to show up on their analytics dashboard, and they'll be seeing links from a campaign they didn't even pay for. If the article gains so much traction, they may reach out to you.<br/></p><p>Organizations have a much larger content marketing budget than most people realize. So as a freelancer, you can write a teaser post about a company. When someone from the company reaches out to you, just be nice and friendly, don't talk about money until the very end. Tell them how you will provide value. After that, you can now ask what their budget is. They might most likely not commit to anything yet, but it's an entry point for you, whatever the outcome might be.</p><h3 id="linda-how-would-you-say-technical-writing-has-impacted-your-career">Linda: How would you say technical writing has impacted your career?</h3><p><strong>William:</strong> Hmmm… I think I wouldn't be where I am now if it wasn't for technical writing. As I said, I initially started out as a software engineer, but then I found technical writing, and it does two things: it validates and amplifies my skills.</p><hr><p><em>And that's all from William. If you'd like to connect with william, reach out to him on <a href="https://twitter.com/iChuloo">Twitter</a>. <br/></em><br><em><em>You can also read other episodes of The Tech Content Creator series <a href="https://www.everythingtechnicalwriting.com/tag/interviews/">here</a>.</em></em></br></p><p><em>Lastly, you can also read the article on <a href="https://www.everythingtechnicalwriting.com/freelance-technical-writing/">freelance technical writing</a> to learn more about how to build up your technical writing portfolio and earn some cool bucks at the same time. </em><br/></p></hr></hr>]]></content:encoded></item><item><title><![CDATA[How to create a Technical Writing Portfolio]]></title><description><![CDATA[Whether you’re looking to land a full-time technical writing job or freelance
contract, you’ll almost always be asked to submit your technical writing
portfolio. 

A technical writing portfolio is your opportunity to show your potential
employers the range of your writing abilities, thought processes, and other
valuable complimenting skills. It could be the decisive factor in whether you
get invited to an interview.

Tom Johnson of I’dratherbewriting
[https://idratherbewriting.com/2009/12/21/get]]></description><link>https://www.everythingtechnicalwriting.com/technical-writing-portfolio/</link><guid isPermaLink="false">Ghost__Post__624ffbc1f01af5001d8b8a0b</guid><category><![CDATA[Introductory]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Fri, 08 Apr 2022 09:57:14 GMT</pubDate><media:content url="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/etw-port.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/etw-port.png" alt="How to create a Technical Writing Portfolio"/><p>Whether you’re looking to land a full-time technical writing job or freelance contract, you’ll almost always be asked to submit your technical writing portfolio. </p><p>A technical writing portfolio is your opportunity to show your potential employers the range of your writing abilities, thought processes, and other valuable complimenting skills. It could be the decisive factor in whether you get invited to an interview.</p><p>Tom Johnson of <a href="https://idratherbewriting.com/2009/12/21/get-a-job-in-technical-writing-step-4-put-together-a-portfolio/" rel="noreferrer nofollow noopener">I’dratherbewriting</a> once mentioned that his portfolio was what got him his first tech writing job, even though he wasn’t the most experienced of the bunch. </p><p>In this article, I’ll share some best practices to keep in mind when putting together your tech writing portfolio. I'll also try to provide answers to some of the most common questions I've received regarding creating a technical writing portfolio.</p><h2 id="creatingselecting-samples-for-your-technical-writing-portfolio">Creating/selecting samples for your technical writing portfolio</h2><p>A technical writing portfolio is simply a showcase of your best tech writing samples and should contain at least 3-5 samples.</p><p>Regardless of your level of experience, here are some general guidelines to keep in mind when putting together your samples:</p><ul><li><strong>Put your best foot forward</strong>: As I said, your tech writing portfolio should be a showcase of your best technical writing samples. But how do you even know what your best writings are? They're the ones where you took a topic that was really complex (and very foreign) and wrote something that made the topic ridiculously easy to understand; the ones for which you've received several positive feedback.</li><li><strong>Showcase different types of writing</strong>: Technical writers in the software industry create different types of writings, such as tutorials, conceptual or explainer guides, reference documents, API docs, e.t.c. Your portfolio should feature different types of writings to demonstrate flexibility.</li><li><strong>Showcase samples relevant to the technical writing niche you want to work in</strong>: Employers want to see that you can produce the kind of content they’re looking for. If you want to work in developer documentation, then your samples should be focused on developer docs. If you want to work in user-focused docs, then your samples should be in that line. And if you want to work in developer marketing or technical content marketing, then the majority of your samples should also follow that line.</li><li><strong>Keep your samples brief</strong>: Recruiters or hiring managers want to be able to quickly see that you have the skills they’re looking for. So, as much as possible, keep your writing samples brief (1000 -1500 words) and be sure that they’re easily scannable.</li></ul><h3 id="for-experienced-tech-writers">For experienced tech writers</h3><p>If you've worked as a technical writer before, you'll already have some good writing samples. Choose the projects with interesting backstories and challenges — those that really pushed you to your limits. </p><p>What if most of your writing samples are proprietary, paywalled, or protected by an NDA? This is a question I’ve heard from most technical writers. If that’s the case, then ask your employers if you delete confidential names and information from your work and showcase fragments of it.</p><p>If they ask why, or if you’re planning to leave, just say: “I wanna keep my portfolio updated the same way I keep my resume updated, so I don't lose sight of my work”.</p><p>If they refuse, then you should consider working on samples for the sole purpose of including them in your portfolio, following the recommendations for newbie writers below.</p><h3 id="for-newbie-tech-writers">For newbie tech writers</h3><p>As a newbie tech writer, you probably don’t have any writing samples under your belt. Regardless, you need to create a portfolio to apply for tech writing jobs. Here are some suggestions:</p><ul><li><strong>Contribute to open-source docs on your own</strong>: Many open-source projects need help with docs, so It’s a good place to start. Contributing to open source is a great idea because the skills you get such as usage of Git, GitHub, and Markdown are skills that are used on a daily basis by technical writers across the globe. Here's a <a href="https://www.reddit.com/r/technicalwriting/comments/gcfmuh/a_list_of_open_source_projects_with_volunteer/" rel="noreferrer nofollow noopener">huge list of some open-source communities that need docs help</a> and how you can get started. Also, here’s a <a href="https://opensource.guide/how-to-contribute/" rel="noreferrer nofollow noopener">guide</a> on how to contribute to open-source projects and a <a href="https://gitimmersion.com/" rel="noreferrer nofollow noopener">guided tour</a> to help you learn the fundamentals of git.</li><li><strong>Contribute to open-source docs through curated programs</strong>: Programs like <a href="https://www.outreachy.org/" rel="noreferrer nofollow noopener">Outreachy</a> and <a href="https://developers.google.com/season-of-docs/docs/timeline" rel="noreferrer nofollow noopener">Google Season of Docs</a>, are designed to help people contribute to open source docs in a structured manner and under the guidance of mentors.</li><li><strong>Freelance tech blogging</strong>: You could also write tutorials or explainer articles for some of the tech publications or content agencies mentioned in my ‘<a href="https://www.everythingtechnicalwriting.com/freelance-technical-writing/" rel="noreferrer nofollow noopener"><em>how to make money as a freelance tech writer</em></a>’ article.</li><li><strong>Do documentation revamps</strong>: Take a look at some poorly written documentation, and rewrite it to make it better. Then in your portfolio, discuss refinements you made and why.</li><li><strong>Self-write/volunteer</strong>: You can start publishing articles or tutorials about your favourite tech products. You can also volunteer to create user guides/ documentation/ articles for your favourite startups. Who knows? They might just even end up hiring you.</li></ul><h2 id="presenting-your-technical-writing-portfolio">Presenting your technical writing portfolio</h2><p>Now that you’ve successfully created/gathered sample writings for your tech writing portfolio, how do you present it? Where do you host it? Here are some ideas:</p><ul><li>A markdown file in your personal repo (GitHub or GitLab).</li><li>A dedicated page on your personal website or blog.</li><li>A notion doc</li></ul><p>Another thing to keep in mind is to give context to all your writing samples. Don’t just present a list of links. For each of your samples, tell the behind-the-scenes story.</p><ul><li>Why are you proud of this piece of content</li><li>What challenges did you face during the course of its creation</li><li>What skills (save for writing) did you have to employ to get the job done?</li><li>What's the impact of the content? What problems did it solve? e.t.c</li><li>What tools did you use?</li></ul><p>All this information serves to give recruiters more details about you, your writing process, and your thought process.</p><p>For example, in my own technical writing portfolio (which I cannot link to because it contains some NDA samples), I highlight one of the documents I wrote for a data pipeline startup. I stated that I was particularly proud of that document because prior to that, I had never heard of the startup's product or a data analytics pipeline. So, it took a lot of researching and interviewing the company's engineers, marketers, and users to write that piece. And in the end, it turned out so well.</p><h2 id="last-words">Last words</h2><p>Start creating that tech writing portfolio now. Don’t procrastinate. Start now.</p><p>Here’s <a href="https://www.youtube.com/watch?v=crePAmhdpww">six example technical writing portfolios</a> in case you need some inspiration.</p><p>Remember to be obsessive in your proofreading. Make sure to eliminate any spelling, grammar, or typographical errors. Don’t give the hiring manager an easy way to disqualify your application!</p><p>Good luck! And if you need someone to look through your portfolio, you can always reach out to me on <a href="https://twitter.com/_MsLinda">Twitter</a>. </p><p>For more tips to help you become a better technical writer and grow in your career, subscribe to my newsletter below!</p><h3 id="further-reading">Further reading</h3><ul><li><a href="https://www.writethedocs.org/videos/portland/2018/document-yourself-practical-tips-for-a-low-er-stress-portfolio-erin-grace/" rel="noreferrer nofollow noopener">Document yourself. Practical tips for low(er) stress portfolio</a></li><li><a href="https://www.youtube.com/watch?v=crePAmhdpww">6 Inspiring Technical Writing Portfolios (+ my new portfolio)</a></li></ul>]]></content:encoded></item><item><title><![CDATA[My review of the Technical Writer Certification Course from Technical Writer HQ.]]></title><description><![CDATA[If you google for recommendations on Technical Writing certification courses,
you'll find the Technical Writer Certification Course
[https://technicalwriter.teachable.com/p/home?referral_code=6TJ7SI] from
Technical Writer HQ featured in 8 out of 10 sites. In fact, I also recommend it
as one of the courses for newbie technical writers in my blog post 'Everything
You Need to Know About Technical Writing
[https://www.everythingtechnicalwriting.com/everything-you-need-to-know-about-technical-writing]]></description><link>https://www.everythingtechnicalwriting.com/review-of-the-technical-writer-certification-course/</link><guid isPermaLink="false">Ghost__Post__624ed6ead3e7a8001dab150f</guid><category><![CDATA[Reviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Thu, 07 Apr 2022 12:40:34 GMT</pubDate><media:content url="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/review-png.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/review-png.png" alt="My review of the Technical Writer Certification Course from Technical Writer HQ."/><p>If you google for recommendations on Technical Writing certification courses, you'll find the <a href="https://technicalwriter.teachable.com/p/home?referral_code=6TJ7SI">Technical Writer Certification Course</a> from Technical Writer HQ featured in 8 out of 10 sites. In fact, I also recommend it as one of the courses for newbie technical writers in my blog post '<a href="https://www.everythingtechnicalwriting.com/everything-you-need-to-know-about-technical-writing/"><em>Everything You Need to Know About Technical Writing</em></a>'.</p><p>One day, one of my Twitter followers asked me what I thought of Technical Writer HQ's Technical Writer Certification Course and whether it was worth the money. To provide an honest review, I purchased and completed the course.</p><h2 id="about-the-course">About the course</h2><p>The Technical Writer HQ's Technical Writer Certification course costs <strong>$299</strong>. It is hosted on the teachable platform, so you can complete it at your own pace.</p><p>The course claims that it will teach you:</p><ul><li>the fundamentals of technical writing,</li><li>how to create great documentation,</li><li>how to answer technical writing interview questions, and</li><li>how to stand out in the interviewing process to land a technical writing job.</li></ul><p>Most sections of the course include exercises as well as answers that you can compare to your own to evaluate yourself.</p><p>You are required to complete a capstone project featuring seven different forms of documentation discussed during the course. You are also required to submit your capstone project to the course creator for feedback.</p><p>After you submit your capstone project, you'll receive feedback on the quality of your work and your certificate of completion. There'd be no certificate if you don't submit your capstone project.</p><h2 id="my-review">My Review</h2><h3 id="the-good">The good:</h3><p>This course will be valuable to you if you are utterly new to technical writing. It does deliver on its promise to teach the fundamentals of tech writing. You'll learn what it means to be a tech writer, different technical writer roles, and some key principles/techniques that you should be aware of in order to succeed as a technical writer.</p><p>Additionally, you'll learn some invaluable editing tips to improve the overall presentation of your writing. You'll also learn how to write a technical writer's resume, negotiate your salary, and answer common technical writer interview questions, among other things you'll need when interviewing for a tech writer role.</p><h3 id="the-bad">The bad</h3><p>I feel the course falls short in teaching how to actually write documentation.</p><p>First, the course is heavily theoretical and delivered in a monotonous narrative tone. It was like the creator was reciting the course content from a whiteboard or paper. I got super bored on several occasions and almost slept off. I would have preferred to read instead.</p><p>Secondly, most parts of the course just felt inconsistent and thrown together without adequate practical instructions. For example, in the section on 'how to document an API', I assumed that we'll be shown practical steps on how to write API documentation. Instead, I got a 7-minute recital of the factors to consider when deciding whether to document a third-party API integration.</p><p>I also expected hands-on demonstrations on how to write the different types of documentation mentioned in the course. I hoped that the creator would use any software product as a case study and then show how he would go about creating the different types of documentation — thoughts processes, note jotting, errors, the whole package. Instead, what I got was the definitions of each type of document, why it was important, and a sample of what it looks like.</p><p>The course also failed to focus on a single niche of technical writing, namely software, and instead seemed to be all over the place, occasionally discussing hardware, medical equipment, and so on. It also sometimes shifted from software documentation to proposal writing. I'm not sure how those relate, but I guess the same principles apply.</p><h1 id="conclusion">Conclusion</h1><p>As I mentioned, this course will be good for total beginners.</p><p>However, if you're like me, and you have some experience with any form of technical writing, I doubt this course will be helpful to you. But, I did enjoy the last sections of the course on editing and proofreading, salary negotiations, and the interviews with technical writers at top organisations like Google, Spotify, Oracle, and Amazon.</p><p>I hope this review helps you decide whether this course will be right for you or not. If you do decide to purchase it, use <a href="https://technicalwriter.teachable.com/p/home?referral_code=6TJ7SI">my link</a> to get 20% off.</p>]]></content:encoded></item><item><title><![CDATA[TCCS #3 From Staff Technical Writer to Developer Advocate; Read Amruta Ranade’s story]]></title><description><![CDATA[Amruta Ranade is a Staff Technical Writer at Airbyte. In this episode, she talks about her journey from becoming a technical writer to a developer advocate, as well as valuable tips for career growth & promotions.]]></description><link>https://www.everythingtechnicalwriting.com/from-staff-technical-writer-to-developer-advocate-read-amruta-ranades-story/</link><guid isPermaLink="false">Ghost__Post__622898a657b80b001d6a2825</guid><category><![CDATA[Interviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Wed, 09 Mar 2022 12:35:45 GMT</pubDate><media:content url="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/techcontentseries.png" medium="image"/><content:encoded><![CDATA[<blockquote><em>The Tech Content Creator Series is a monthly interview series in which I interview people in technical content creation roles (i.e. technical writers, documentation engineers, developer advocates, and what have you) about their careers. My hope is for their stories to inspire, motivate, and hopefully impact you.</em></blockquote><img src="https://res-3.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/techcontentseries.png" alt="TCCS #3 From Staff Technical Writer to Developer Advocate; Read Amruta Ranade’s story"/><p>My guest for this episode was <a href="https://twitter.com/AmrutaRanade" rel="noreferrer nofollow noopener">Amruta Ranade</a>. Amruta is an OG in the technical writing field. She holds a masters degree in technical communication and has worked as a Technical Writer for over ten years, progressing from Technical Writer to Senior Technical Writer to Staff Technical Writer to Developer Advocate and back to Staff Technical Writer.</p><p>In this episode, she talks about how her transition from Technical Writer to Developer Advocate back to Technical Writer. She also shares how she ensures growth in her career and other insightful career advice that you would find helpful.</p><p>Sit back and enjoy!</p><h3 id="me-lets-talk-about-your-career-journey-how-did-you-get-started-in-technical-writing-up-to-where-you-are-now">Me: Let's talk about your career journey. How did you get started in technical writing up to where you are now?</h3><p><strong>Amruta</strong>: So, my first degree was in Electronic Engineering back in 2009 and my first job out of college was as a VLSI Project Engineer. At this job, one of my responsibilities was to create datasheets for VLSI Power chips. I realised that I enjoyed the datasheet writing aspect of the job to the electronics side of the job.</p><p>So, I quit that job and got my first full-time job as a technical writer for Symantec. I did a summer course on technical writing in college, so I knew what was expected. At Symantec, I worked on end-user documentation. </p><p>After working at Symantec for about 2 years, I came across this opportunity for internal engineering documentation for a startup called Druva. The CTO of the company designed the entire system. He found himself talking about the same thing repeatedly, so he decided to hire a technical writer to write all of that stuff, so he could focus on his actual job. As someone with an engineering background, this sounded more exciting, so I quit my job at Symantec. </p><p>After I had worked as a self-taught technical writer for about 5 years, I said to myself "if I am going to do this for the rest of my career, I should probably get some education on this". At that time, there were no technical writing graduate programs that I knew of in India, so I started looking abroad. I found one in Missouri, USA. I applied and was accepted, and after two years of study, I received my masters degree in Technical Communication.</p><p>Following my graduation, I applied for and was hired for a developer documentation position at Cockroach Labs, which had a mix of internal engineering and end-user documentation. I worked there for almost 5 years and recently left to join Airbyte as their first technical writer to build out the technical writing team.</p><h3 id="me-did-getting-a-masters-in-technical-communication-significantly-impact-your-career-also-is-it-something-you-think-people-that-want-to-really-invest-in-building-a-robust-technical-writing-based-career-should-go-for">Me: Did getting a masters in Technical communication significantly impact your career? Also, is it something you think people that want to really invest in building a robust Technical Writing based career should go for?</h3><p><strong>Amruta</strong>: It did, but not in the way that you would expect. It helped me understand and unpack why all the best practices of technical writing that I knew of were, in fact, the best practices. </p><p>I think I gained a lot from my masters degree because I already had experience as a technical writer. It made me a better technical writer. But, if I didn't have a degree in technical writing, the masters degree would not have served me as well as it did. </p><p>So a masters is not a prerequisite to having a successful technical writing career. But it's an option to consider if your want to expand your knowledge after you've gotten fundamental experience.</p><h3 id="me-do-you-think-your-masters-degree-tips-the-scales-in-your-favour-in-the-job-hunting-phase">Me: Do you think your masters degree tips the scales in your favour in the job hunting phase?</h3><p><strong>Amruta</strong>: That's a very good question considering that I'm hiring now, and I'm wondering if I should give more attention to resumes with certificates. </p><p>Honestly, I think I would base the decision on their portfolio. If you have a master's degree and don't have a strong portfolio, it is merely a stamp on a paper. </p><h3 id="me-ok-tricky-question-assume-you-have-two-candidates-with-comparable-portfolios-and-depth-of-expertise-however-one-holds-a-masters-degree-in-technical-communication-while-the-other-does-not-which-will-you-choose">Me: OK. Tricky question. Assume you have two candidates with comparable portfolios and depth of expertise. However, one holds a master's degree in technical communication while the other does not. Which will you choose?</h3><p><strong>Amruta</strong>: I will invite both of them to the interview. Again a master's degree can get you in the door for an interview. Still, if you don't perform well, it's equivalent to having a degree but not being able to do the job.</p><p>The interview will show who is more suited to the job. The interview will evaluate collaboration skills, time management skills, and other important skills that you don't necessarily get from a masters degree.</p><h3 id="me-lets-talk-about-your-career-switch-from-technical-writer-to-developer-advocate-how-did-that-happen-and-what-inspired-you-to-take-that-decision">Me: Let's talk about your career switch from technical writer to developer advocate. How did that happen and what inspired you to take that decision?</h3><p><strong>Amruta</strong>: I had spent like 10 years in Technical Writing, and I got bored. I had moved from senior to staff, and it felt like I had climbed every career ladder, and the next thing was to move to management. But I was way too burnt out on tech writing to be a good manager at that point. </p><p>Developer advocacy is the shiny thing at this time. I had a youtube channel that I so much enjoy, so I thought to myself, 'hey, my current skills align with the necessary skills for this role'. </p><p>My manager was incredibly supportive, and so he was like, "OK, go try it, if you don't like it, you can come back". As I found out, I didn't really enjoy it, but I feel like I would have regretted it if I didn't try it out.</p><h3 id="me-when-you-became-a-developer-advocate-at-cockroach-labs-were-they-hiring-for-the-role-or-was-the-role-created-just-for-you">Me: When you became a developer advocate at Cockroach Labs, were they hiring for the role, or was the role created just for you?</h3><p><strong>Amruta</strong>: Before I officially became a developer advocate role at Cockroach Labs, I had been doing the duties of a developer advocate for a year. </p><p>At Cockroach Labs, we have a culture where Fridays are reserved for experimenting or doing something outside your everyday job obligations. So, during my time as a Staff Tech writer, I used my Fridays to dabble into the duties of a developer advocate for a whole year (creating articles, Twitter memes, hackathons, e.t.c), before I convinced the company that it should be an actual role. </p><p>When they agreed to the role, they interviewed me and passed because I mean, I had been doing the job for a year. I held the developer advocate role officially for a year before deciding that it wasn't for me.</p><h3 id="me-what-made-you-realise-that-dev-advocacy-was-not-for-you">Me: What made you realise that dev advocacy was not for you?</h3><p><strong>Amruta</strong>: In my opinion, the developer advocacy role needs to evolve. Currently, there are a lot of blurry lines, and a lot of things get dumped on developer advocates, which can get very overwhelming. Also, the job involves a lot of administration. </p><p>The thing I missed the most with tech writing is there is an end date; you have a release, you write the documentation, and you're done. With developer advocacy, it was like there was never an end in sight.</p><p>However, this experience helped me become a better technical writer. I got to see how developers used the documentation I had written actually to do the things they needed. It gave me a developer awareness that I previously did not have.</p><h3 id="me-while-writing-documentation-have-you-had-to-write-demo-code-and-how-did-you-handle-that">Me: While writing documentation, have you had to write demo code? And how did you handle that?</h3><p><strong>Amruta</strong>: I ask the developers to do it or contract it out to a development agency. I can build a demo app, but that wouldn't be a very good use of my time because there are other people who can do it better and faster than me. So, I let them, and I focus on creating the content.</p><h3 id="me-does-your-company-make-provision-for-funds-to-hire-agencies">Me: Does your company make provision for funds to hire agencies?</h3><p><strong>Amruta</strong>: Yes. As an immigrant, I am quite frugal. Initially, I was like, 'I should learn it and do it'. But my CMO at Cockroach and my manager at Airbyte were like, "that's not a good use of time. We have the money, and we need you to focus on the job that you're good at".</p><h3 id="me-how-do-you-measure-the-relevance-of-what-you-do-what-gives-you-satisfaction-for-example-software-developers-build-products-and-can-see-users-use-it-and-how-it-impacts-them">Me: How do you measure the relevance of what you do. What gives you satisfaction? For example, software developers build products and can see users use it and how it impacts them.</h3><p><strong>Amruta</strong>: I'll answer this on a personal level because I don't have a universal answer. At Cockroach, my satisfaction came from feedback from our users calling out how good our documentation is. That was the motivation for me, seeing that what I do makes someone's life easier. </p><p>Before that at Druva, which was like an internal thing, I'd have engineers walk up to me like, 'oh hey, that document you created yesterday, thank you'. I even won an award.</p><h3 id="me-based-on-your-experiences-what-resources-would-you-recommend-for-someone-who-wants-to-pursue-a-career-in-technical-writing">Me: Based on your experiences, what resources would you recommend for someone who wants to pursue a career in technical writing?</h3><p><strong>Amruta</strong>: I have resources in the form of books and communities.</p><ul><li><a href="https://www.reddit.com/r/technicalwriting/" rel="noreferrer nofollow noopener">The tech writing subreddit</a>.</li><li><a href="http://<a tahttps://www.amazon.com/Docs-Developers-Engineers-Technical-Writing/dp/1484272161?&amp;_encoding=UTF8&amp;tag=linda45-20&amp;linkCode=ur2&amp;linkId=c969d230b319cf2e9128bc262ba9516b&amp;camp=1789&amp;creative=9325" rel="noreferrer nofollow noopener">Docs for Developers</a></li><li><a href="https://idratherbewriting.com/" rel="noreferrer nofollow noopener">I'd Rather Be Writing blog</a></li><li><a href="https://heroictechwriting.com/" rel="noreferrer nofollow noopener">Heroic Tech Writing Blog</a></li></ul><p>However, you can watch videos and read all the blogs, but you won't get far if you don't practice. </p><p>If you want to become a technical writer, write technical documents. There's no other way around it. Write a how-to guide on how to play wordle or a conceptual document on what NFTs are. This will help you find out if its something you even like. </p><p>You don't become a technical writer by getting a technical writing job. You become a technical writer before getting the official title. I feel like people get too hung up on how do I get a job without wanting to do what it takes to become a technical writer who can now get a job as a tech writer. </p><p>Also, hang out in forums where technical writers hang out. Participate in discussions, and learn more about the industry.</p><h3 id="me-how-do-you-ensure-growth-in-this-career-path-what-does-one-need-to-do-to-ensure-that-they-keep-on-growing-in-skills-and-rank">Me: How do you ensure growth in this career path? What does one need to do to ensure that they keep on growing in skills and rank?</h3><p><strong>Amruta</strong>: This may sound quite controversial, but my answer is job-hopping. The longest I've stayed in a company was Cockroach Labs, and that's cos I moved roles. <br>I think 2 - 3 years is enough time to learn what you can in a company or a particular role. For me, every 2-3 years, I re-evaluate to see if it's still what I want to do. You have to be honest with yourself. You'll know when you're getting stagnant. </br></p><p>There are two aspects of growth in a career: title and pay. It's easier to get a title level-up at your current company but if you want a salary level-up, go to another company. </p><p>I went from Senior to Staff in Cockroach Labs, but the significant pay raise came when I switched jobs. Every time I job hopped, my salary has almost always doubled. In the tech industry, that's the only substantial way that I know of to get significant raises.</p><h3 id="me-youve-moved-from-technical-writer-to-senior-technical-writer-to-staff-technical-writer-how-did-you-convince-management-that-it-was-time-for-you-to-move-to-the-next-level">Me: You've moved from technical writer to senior technical writer to staff technical writer. How did you convince management that it was time for you to move to the next level?</h3><p><strong>Amruta</strong>: I'm always honest with my managers. Suppose there's a performance review coming up next year, and I'm expecting a promotion. I start letting them know from this year that I would like to be promoted, asking what I can do to get there. </p><p>You get a promotion when you're already performing at that level. It's not an 'oh come and do this job', it's an 'oh you're already doing this job, alright, here's the title to go along with it'.</p><h3 id="me-lets-talk-about-career-progression-say-someone-has-been-a-technical-writer-for-a-few-years-and-wants-to-move-into-another-vertical-in-the-software-industry-what-roles-can-they-comfortably-move-into-based-on-their-skillset-i-know-developer-advocacy-is-one">Me: Let's talk about career progression. Say someone has been a technical writer for a few years and wants to move into another vertical in the software industry. What roles can they comfortably move into based on their skillset (I know developer advocacy is one)?</h3><p><strong>Amruta</strong>: You can move in product management or agile coaching (popular in the indian ecosystem). There's also UX writing roles or full time management.</p><h3 id="me-last-question-do-you-have-any-tips-or-unpopular-opinions-you-would-like-to-share">Me: Last question, do you have any tips or unpopular opinions you would like to share?</h3><p><strong>Amruta</strong>: Oh, I have a popular opinion that I don't tend to voice out a lot. Technical writing is a very nice field, with a really really welcoming community. <br>If you're interested in building your technical writing portfolio, Amruta has a <a href="https://www.techwritingacademy.com/technical-writing-workshop" rel="noreferrer nofollow noopener">portfolio building workshop</a>. Also, check out <a href="https://www.youtube.com/c/AmrutaRanade" rel="noreferrer nofollow noopener">her YouTube channel</a>.</br></p><p>See you at the next episode!</p>]]></content:encoded></item><item><title><![CDATA[How to write content that readers will read based on learnings from user psychology]]></title><description><![CDATA[Learn how to tailor your content to align with how users read on the web, in order to capture their attention and get them to read it.]]></description><link>https://www.everythingtechnicalwriting.com/how-to-write-content-that-readers-will-read/</link><guid isPermaLink="false">Ghost__Post__6226fdeb559276001d3e12a7</guid><category><![CDATA[Content Tips]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Tue, 08 Mar 2022 07:00:18 GMT</pubDate><media:content url="https://res-4.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/content.png" medium="image"/><content:encoded><![CDATA[<img src="https://res-4.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/content.png" alt="How to write content that readers will read based on learnings from user psychology"/><p>According to research, users read through the content on a webpage <a href="https://www.nngroup.com/articles/how-users-read-on-the-web/" rel="noreferrer nofollow noopener">only 16% of the time</a>. The reason is that most web content is not optimized for the way users on the web read. </p><p>Imagine this: you just wrote and published something you consider to be your best piece of writing yet. You also employed tactics like SEO, social media sharing, and email lists to drive traffic to your writing.</p><p>However, weeks/months go by, and all you can see on Google Analytics is an increase in bounce rates and a decrease in average session duration. That could be due to one of two factors: users are getting immediate value out of your content, or they're just not reading through.</p><p>In this article, you will learn:</p><ul><li>How users evaluate content on the web to decide whether it's worth reading.</li><li>How to adapt your writing to the way users read on the web to improve readability and give your audience a reading experience that they will appreciate.</li></ul><h2 id="how-users-decide-whether-to-read-a-piece-of-content-or-not">How users decide whether to read a piece of content or not</h2><p>The truth is, for users to read your content, it had to grab their attention and convince them that it can deliver value to them. </p><p>Last year, out of curiosity, I enrolled in a digital psychology mini degree offered by <a href="https://cxl.com/" rel="noreferrer nofollow noopener">CXL Institute</a>. Digital psychology is a tiny branch of psychology that seeks to understand how and why humans behave the way they do on the web. </p><p>During the course of this mini degree, I studied the results of several experiments conducted by scientists and psychologists on <strong>How Users Read on the web.</strong> This article is based on everything I learned.</p><p>To understand why users may still not read your content, even when you've nailed SEO, let's look at a typical content search discovery journey (i.e. how users go from discovering a piece of content through search to actually reading it). <br/></p><figure class="kg-card kg-image-card"><img src="https://paper-attachments.dropbox.com/s_761738E7D2307E74F233F7F74A50CF4BBC1D8249C6C3128A74CF4C8D4DA00365_1646021805917_Screenshot+2022-02-28+at+05.15.47.png" class="kg-image" alt="How to write content that readers will read based on learnings from user psychology" loading="lazy"/></figure><p><br>From the flowchart, it's evident that to increase the chances of users to read through a piece of content, the content needs to:</br></p><ul><li>grab their attention, and</li><li>Satisfy the considerations users carry out to determine if it is worth reading.</li></ul><p>So, what do users consider to determine if a piece of content is worth reading?<br> When users encounter a piece of content, they usually examine the content, considering the following factors before deciding whether to read it:</br></p><ul><li>Is this piece of content relevant or useful to me?</li><li>Is it credible?</li><li>Is it going to provide the value I'm looking for?</li></ul><p>Note that this decision-making process happens automatically in seconds.</p><h2 id="tips-thatll-increase-the-chances-of-readers-reading-your-content">Tips that'll increase the chances of readers reading your content</h2><p>Based on the typical reader content search discovery journey discussed above, it's evident that it takes more than writing great content to get it to be read. <br>Here are some guidelines you can follow to adapt your writing to the way users read on the web so that they'll be more likely to read it.</br></p><h3 id="1-make-your-titles-relevant">1. Make your titles relevant</h3><p>The title of a piece of content is the first thing readers see in the content discovery phase in places such as search results, social-media streams, blog feeds, e.t.c. It's the first thing users consider to determine if a piece of content is likely to be relevant and valuable to them. </p><p>So, to grab the attention of your target reader, ensure that your titles are specific, descriptive, and communicates the value your content will provide them. </p><p>For example, consider the following titles: <br><br>a. <strong>Everything a product manager needs to know about APIs to better communicate with developers </strong><br><br>b. <strong>5 things you can do with an API</strong><br><br>Assuming you were a product manager looking for information about APIs, which would you click on first? <br><br>I'm guessing the first one because it's specific to you informs you what value you'll get from the content, which is 'the ability to better communicate with your developers'.</br></br></br></br></br></br></br></br></p><h3 id="2-make-the-value-proposition-of-the-content-clear">2. Make the value proposition of the content clear</h3><p>When users land on a piece of content, one of the first things they do is scan the content to further determine if the content will be relevant or useful to them.</p><p>A value proposition is a simple description of what a reader will get out of reading your content (i.e. what they will learn). </p><p>Users often leave Web pages in 10–20 seconds, but pages with a clear value proposition can hold a user's attention for much longer. </p><p>To improve the chances of users reading your content, you should clearly communicate your value proposition within 10 seconds; preferably within the first two paragraphs. </p><p>Here are examples of technical content that clearly communicate their value proposition in their beginning paragraphs:<br/></p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://paper-attachments.dropbox.com/s_761738E7D2307E74F233F7F74A50CF4BBC1D8249C6C3128A74CF4C8D4DA00365_1646031386970_Screenshot+2022-02-28+at+07.44.29.png" class="kg-image" alt="How to write content that readers will read based on learnings from user psychology" loading="lazy"><figcaption>Article from didicodes</figcaption></img></figure><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://paper-attachments.dropbox.com/s_761738E7D2307E74F233F7F74A50CF4BBC1D8249C6C3128A74CF4C8D4DA00365_1646031426584_Screenshot+2022-02-28+at+07.46.20.png" class="kg-image" alt="How to write content that readers will read based on learnings from user psychology" loading="lazy"><figcaption>Stripe's documentation</figcaption></img></figure><h3 id="3-go-for-simple-clutter-free-webpage-layouts">3. Go for simple, clutter-free webpage layouts</h3><p>According to <a href="https://www.nngroup.com/reports/how-people-read-web-eyetracking-evidence/?lm=how-users-read-on-the-web&amp;pt=article" rel="noreferrer nofollow noopener">some eye-tracking test studies</a>, one of the first things users observe when they land on a webpage is its look and feel or layout. It helps them decide if the webpage is credible and if the content of the webpage is worth reading.</p><p><br>I'd always had this hunch even before reading about this behaviour, so I polled my co-workers to confirm. I asked if site design and structure influenced whether they read a blog post after clicking on it from a Google search result. As it turns out, it does.</br></p><figure class="kg-card kg-image-card kg-card-hascaption"><img src="https://cdn-images-1.medium.com/max/1600/1*hI2UfhCdqUypN_cQ50oyvg.png" class="kg-image" alt="How to write content that readers will read based on learnings from user psychology" loading="lazy"><figcaption>screenshot of my conversation with my co-workers</figcaption></img></figure><p><br>Factors like small fonts, lack of whitespace, cramped pages, and low colour contrast decreases legibility and contributes to page clutter. Page clutter increases cognitive load, which overwhelms readers and eventually causes them to jump ship. </br></p><p>So, what can you do? </p><ul><li><strong>Avoid cluttered page designs</strong>. Go for a simple, minimalistic layouts that incorporates a lot of whitespace and a maximum of 3 grid columns for your blog and documentation pages.</li><li><strong>Use legible typefaces</strong>. Unusual-shaped fonts (e.g., those that emulate handwriting or gothic style) impair readability.</li><li><strong>Have high contrast between text and background</strong>. Preferably, use a plain background instead of a busy or textured one, since the latter also impairs legibility.</li><li><strong>Use a reasonably large default font size</strong> and allow users to change the font size. Tiny text dooms legibility.</li></ul><p><br>Granted, these are not activities that you may be able to influence as a technical writer (it's more of a designer's or developer's job), but you can always raise concerns and recommendations</br></p><h3 id="4-optimize-your-content-for-scanning-and-skimming">4. Optimize your content for scanning and skimming</h3><p>When a user lands on a piece of content, their intention is to either find a solution to a problem or learn about a concept in the shortest amount of time possible. So, they scan to see if the content contains valuable information relative to their needs. If the content does contain information that's relevant to them, they'll then settle down to read. If it doesn't, they bounce.</p><p>Optimizing your content for scanning ensures that users can find information that's most relevant to them quickly. </p><p>To optimize for scanning, do the following:</p><ul><li><strong>Use descriptive subheadings</strong> that concisely reflect the subject of a section.</li><li><strong>Include a table of contents</strong>, if applicable, so readers can easily navigate to the areas that are most relevant to them.</li><li><strong>Highlight key ideas or information</strong> that will be of interest to readers within sections or paragraphs with bold words, underlined text, coloured words, capital letters, etc</li><li><strong>Use short sentences and paragraphs</strong>. Long sentences/paragraphs are difficult to scan, and put a strain on users' short-term memory,</li><li><strong>Write in an inverted-pyramid style</strong>; each section should begin with a summary of the most critical points. This enables readers to locate the information they're looking for quickly.</li><li><strong>Group your writing into sections or paragraphs that emphasize just one key point or idea</strong>. This aids comprehension and reduces cognitive load, as the human brain can only concentrate on a few things at a time.</li></ul><h1 id="when-it-comes-to-content-less-is-always-more">When it comes to content, less is always more</h1><p>Based on all the points discussed above, one thing is clear: <strong>the lesser the cognitive friction or load associated with a piece of content, the more likely users will read it</strong>. </p><p>You can lower the cognitive load associated with your content by looking out for opportunities to make the content more scannable, concise, and succinct, so that readers can quickly locate the information they need.</p><p>Incorporating the four tips discussed above into your writing creates a better reading experience for your readers. Also, it showcases that you possess empathy, which is a critical trait for a technical writer to have.</p><p><a href="https://www.nngroup.com/articles/how-users-read-on-the-web/" rel="noreferrer nofollow noopener">NNGroup conducted an experiment </a>to measure the effectiveness of some of the content guidelines outlined above. The result was a whopping 124% increase in readability. This could be your story too.</p><h3 id="further-reading">Further Reading:</h3><ul><li><a href="https://www.nngroup.com/articles/how-users-read-on-the-web/" rel="noreferrer nofollow noopener">How users read on the web</a></li><li><a href="https://www.nngroup.com/articles/headings-pickup-lines/" rel="noreferrer nofollow noopener">Headings Are Pick-Up Lines: 5 Tips for Writing Headlines That Convert</a></li><li><a href="https://www.nngroup.com/articles/legibility-readability-comprehension" rel="noreferrer nofollow noopener">Legibility, Readability, and Comprehension: Making Users Read Your Words</a></li><li><a href="https://www.nngroup.com/articles/information-foraging/" rel="noreferrer nofollow noopener">Information Foraging: A Theory of How users Navigate on the web</a></li><li><a href="https://www.nngroup.com/topic/writing-web/" rel="noreferrer nofollow noopener">The entire NNGroup content archive on writing for the web</a></li></ul>]]></content:encoded></item><item><title><![CDATA[2 ways to make money as a freelance technical writer]]></title><description><![CDATA[Whether you're a newbie developer or an experienced developer looking to make
some extra bucks on the side, freelance technical writing is the way. As a
freelance technical writer, you can make anywhere from $100 to $800 per article,
depending on the complexity.

When I first started out in tech as a Frontend developer, I was able to earn an
extra $1200 - $2000 per month by writing technical articles. How did I do it?
Well, that's what I'm about to share with you.

N.B: The methods discussed bel]]></description><link>https://www.everythingtechnicalwriting.com/freelance-technical-writing/</link><guid isPermaLink="false">Ghost__Post__62138ecb66274a001db921e2</guid><category><![CDATA[Introductory]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Thu, 10 Feb 2022 12:36:18 GMT</pubDate><content:encoded><![CDATA[<p>Whether you're a newbie developer or an experienced developer looking to make some extra bucks on the side, freelance technical writing is the way. As a freelance technical writer, you can make anywhere from $100 to $800 per article, depending on the complexity.</p><p>When I first started out in tech as a Frontend developer, I was able to earn an extra $1200 - $2000 per month by writing technical articles. How did I do it? Well, that's what I'm about to share with you.</p><p><em><strong>N.B:</strong> The methods discussed below apply only to technical writers who also double as software developers, or have considerate software development knowledge.</em></p><h2 id="method-1-guest-writing-for-popular-developer-publications">Method 1: Guest writing for popular developer publications</h2><p>The most common way to make money from writing technical articles is to guest write technical articles for developer blogs like Logrocket, Smashing Magazine, or CSS tricks. As part of their content marketing strategy, these companies/publications pay developers to write technical articles for them to drive search traffic to their sites.</p><p>Here is a list of over <a href="https://blog.idrisolubisi.com/get-paid-to-write-for-these-45-websites" rel="noreferrer nofollow noopener">45+ developer publications that have guest writer programs</a>.</p><p>Typically, the process is that you pitch an article idea. If your pitch is accepted, you'll be given the go-ahead to write the full article and get paid, pending when the article is published. </p><h3 id="how-to-pitch-an-article-idea">How to pitch an article idea</h3><p>I'm sure this is the next question on your mind. The answer is that each of these publications has specific guidelines for becoming a guest writer. You'll typically find these instructions on their 'write-for-us' page, where you'll be asked to pitch an article.</p><p>Sometimes, these publications may have their own specific topics that they want guest writers to write about. Other times, you're free to pitch your own topic idea. <br>To increase the chances of your pitch being accepted, think of something that's from a unique perspective and hasn't been written about in that publication. </br></p><p>For example, say there was a concept within the constraints of the publication's theme that you found challenging to understand but later understood. You could write about that concept from your perspective and how you could finally understand it.</p><p>Your article pitch should include:</p><ul><li>Your proposed article topic</li><li>Why the topic is relevant to the publication</li><li>Summary of what the article will be all about</li><li>What the audience will learn from the article, and</li><li>Why you're the right person to write about the topic</li></ul><p>Here's a template or example of an article pitch: </p><p><em>Hello, my name is [your-name]. I am a [job-title or experience-relevant-to-tech-writing]. I'd love to guest write for your publication. </em></p><p><em>[insert-your-article-topic-idea-here]</em></p><p><em>E.g: Here's the topic I'd love to write about: How to create stunning talk slides with reveal.js </em></p><p><em>[insert-why-the-topic-is relevant-to-the-publication-target-audience-here]</em></p><p><em>E.g: These days more developers are applying to give talks at conferences, either to boost their public brand or grow their network. Popular presentation tools like Google Slides do not allow developers to fully tap into their creative sides. That's where Reveal.js comes in. </em></p><p><em>[insert-summary-of-what-the-article-is-about-here]</em></p><p><em>E.g: Reveal.js is an open source HTML presentation framework. It's a tool that enables anyone with a web browser to create fully-featured and beautiful presentations for free. Anything you can do on the web can be done in reveal.js presentations. You can change styles with CSS, include an external web page using an &lt;iframe&gt; or add your own custom behaviour using the JavaScript API. </em></p><p><em>[insert-what-readers-will-learn-here]</em></p><p><em>E.g: In this article, readers will learn how to:</em></p><ul><li><em>Set up Reveal.js on their local machines</em></li><li><em>Navigate the Reveal.js editor</em></li><li><em>Create their first slides</em></li><li><em>Add animations to their slides using the JavaScript API, and finally</em></li><li><em>Deploy their slides to the public.</em></li></ul><p><em>[insert-why you’re-the-right-person-to-write-about-the-topic-here]</em></p><p><em>E.g: I recently just used Reveal.js to build slides for my recent talk which I gave at the just concluded ReactCon Live conference, and a lot of people loved it. Also, here's a link to other articles I've written to help you ascertain my tech writing abilities. </em></p><p>The goal of the article pitch is to convince the publication to take a chance on you. Make it worthwhile. </p><h2 id="method-2-write-as-a-contractor-for-technical-content-marketing-agencies">Method 2: Write as a contractor for technical content marketing agencies</h2><p>Writing for developer publications is great, but the truth is that your pitch may not be accepted due to a couple of factors like:</p><ul><li>Your pitch does not align with the publication's content calendar direction for the month, or</li><li>Someone else has pitched a similar idea</li></ul><p>Technical content marketing agencies are agencies that produce technical content on behalf of other tech companies to help them drive traffic, gain visibility, generate leads, and hopefully drive sales. Opting to write as a contractor for technical content marketing agencies offers you more structure. You also get to enjoy benefits like: </p><ul><li>You don't need to pitch articles. The agency usually sends out a list of article topics that have been pre-approved by their clients. Yours is to indicate interest and have the article assigned to you.</li><li>Depending on your niche, schedule, and familiarity with most topics, you can write as many as 4 or 5 articles per month, allowing you to make a steady income.</li><li>You'll be presented with several opportunities to conduct intensive research, learn new things and write articles that are way out of your comfort zone.</li></ul><p>To join a technical content marketing agency as a freelance/contract writer, you'd typically be asked to provide a technical writing portfolio, or sample articles that you've written. So, to increase your chances of being selected, make sure that you have previous concise technical articles under your name. </p><p>Now the question is, how do you find these technical content marketing agencies? A little digging around on Google search may yield more valuable results, but here are a few that I am aware of:</p><ul><li><a href="https://draft.dev/write">Draft.dev</a></li><li><a href="https://contentlab.io/writeforus/">ContentLab</a></li><li><a href="https://writefordev.com/#first-page">Write for Dev</a></li><li><a href="https://www.hitsubscribe.com/apply-to-be-an-author/">Hit Subscribe</a></li><li><a href="https://www.devspotlight.com/jobs/">Dev Spotlight</a></li><li><a href="https://docforce.io/careers/" rel="noreferrer nofollow noopener">Docforce</a></li><li><a href="https://documentwrite.dev/services/" rel="noreferrer nofollow noopener">DocumentWrite</a></li><li><a href="https://compose.ly/become-a-writer/">Compose.ly</a></li></ul><h2 id="build-up-your-portfolio-with-freelance-technical-writing">Build up your portfolio with freelance technical writing</h2><p>Aside from making extra income, another advantage of writing articles for developer publications or technical content marketing agencies is the opportunity to work with professional editors, which allows you to improve your writing skills. You'd also be developing your technical writing portfolio in preparation for applying for full-time tech writing positions.</p><p>If you do decide to pursue freelancing full-time, consider taking this <a href="https://academy.zerotomastery.io/a/aff_r3sfzzqq/external?affcode=441520_tjxt0mkj">course on freelancing</a> taught by a top-rated Upwork freelancer to learn strategies to start freelancing, build an online presence, and get high-paying clients.</p><p><a href="https://www.getrevue.co/profile/_mslinda">Subscribe to my newsletter</a> if you'd like to receive a monthly list of technical writing opportunities (both freelance and full-time) in your inbox!</p>]]></content:encoded></item><item><title><![CDATA[TCCS #2: How I became a Technical Writer with Cynthia Peter]]></title><description><![CDATA[> The Tech Content Creator Series is a monthly interview series in which I
interview people in technical content creation roles (i.e. technical writers,
documentation engineers, developer advocates, and what have you) about their
careers. The goal is to inspire, motivate, and hopefully impact you.
This month my guest was Cynthia Peter [https://cynthiapeter.com/]. Cynthia is
currently a Technical Writer at Sterling One bank [https://sterling.ng/onebank/] 
and The [at] company [https://atsign.com/]]></description><link>https://www.everythingtechnicalwriting.com/my-journey-into-technical-writing-with-cynthia/</link><guid isPermaLink="false">Ghost__Post__62138ecb66274a001db921e1</guid><category><![CDATA[Interviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Fri, 04 Feb 2022 16:16:30 GMT</pubDate><content:encoded><![CDATA[<blockquote>The Tech Content Creator Series is a monthly interview series in which I interview people in technical content creation roles (i.e. technical writers, documentation engineers, developer advocates, and what have you) about their careers. The goal is to inspire, motivate, and hopefully impact you.</blockquote><p>This month my guest was <a href="https://cynthiapeter.com/">Cynthia Peter</a>. Cynthia is currently a Technical Writer at <a href="https://sterling.ng/onebank/">Sterling One bank</a> and <a href="https://atsign.com/">The [at] company</a>. At these companies, she works primarily on internal documentation.</p><p>In this episode, she talked about her journey to becoming a technical writer and some tips on how to get gigs on Upwork and scale technical writing interviews. She also talked about her struggles as an undergraduate and teaching computer science to secondary school students in a remote village in Delta State, Nigeria.</p><p>Fun fact: Cynthia knows a bit of Chinese, Spanish, and Polish.</p><h3 id="me-hi-cynthia-thank-you-for-making-time-out-for-this-first-question-how-did-you-get-into-technical-writing">Me: Hi Cynthia, thank you for making time out for this. First question, how did you get into technical writing?</h3><p>(Disclaimer: brace yourself and maybe get some popcorn. I was hoping for a trailer, but Cynthia gave us the whole movie)</p><p><strong>Cynthia</strong>: I studied Computer Science at Federal Polytechnic, Oko, from 2012 to 2017. At first, I didn't like the course, but I just went ahead with it because I didn't want to stay at home with my parents for a year. Back then, despite my lack of exposure, I knew I didn't want to work a 'normal' job. I wanted to work from home, but I didn't know-how. So when I found out that working from home was a possibility with computers, I became more interested in it.</p><p>Fast-forward to my internship year in 2015. My father wanted me to intern at a bank, but I refused and told him I wanted to learn programming. I was taught outdated programming languages and theory in school, so I wanted something more practical. That was how I enrolled in a program at a coding centre. It was at this program that I learnt HTML, CSS, JavaScript, and a bit of PhotoShop. But, I had a bit of a harassment issue, so I stopped going.</p><p>After my internship year, I went back to complete my degree and returned as a blogger.</p><h3 id="me-a-blogger-how">Me: A blogger? How?</h3><p><strong>Cynthia:</strong> So, during my program at the centre, because I had access to unlimited internet, I was googling and learning about other stuff — copywriting, blogging, and just writing in general. I went back to school, and I started writing for this blog. My pay was two thousand naira per month to write at least 10 articles on trending news and gossip.</p><h3 id="me-wait-two-thousand-naira-what-year-was-this">Me: Wait! Two thousand naira? What year was this?</h3><p><strong>Cynthia</strong>: Oh, this was 2016 - 2017, and to me, I was balling yunno. After a while, I quit and started my own blog. But I got hacked, which was quite painful because I had over $300 in my Google AdSense.</p><p>But then I finished school and went back home. My next plan was to travel abroad, but my parents couldn't afford it, so I enrolled in a Chinese class. Lol, I just thought that learning Chinese would one day give me an opportunity to travel out. I have my HSK1, HSK2, and HSK3 certificates.</p><p>After that, I went for my NYSC service. During my service year, I was posted to a remote village in Delta state to teach computer science to children who had never seen a computer before. It was crazy, I had no clue how to go about it, and it was evident that they did not understand what I was saying. But something changed. I noticed that cassava processing was a major activity in the village, so I used an analogy of processing cassava to explain how a computer works to the children. I was like, "you all know how you take cassava in bags to the processing farm, put the cassava in the processing machine, and it gives you a paste in return; that's exactly how a computer functions". And they were all like, "oh, that's what you mean by computer is an electronic device that processes data".</p><p>Now, I like to think that that was my intro to technical writing — like my technical writing 101. Being able to break down those technical concepts and processes to the level of understanding of my target audience (which were the students).</p><p>That phase passed. In 2019, I finished service, and I moved to Port Harcourt. One day, I tagged along with a friend to his workplace. While I was there, they were brainstorming about an e-store app they wanted to build. I started asking questions about scenarios that they weren't considering in their discussion from the corner where I was seated. Then the CEO beckoned on me to come closer. My friend had previously mentioned that I write, so he asked me if I'll be willing to write for them — like documenting the product. It was an unpaid engagement. But, I got free internet, and it was here that I started learning flutter because the CEO bought me a flutter course.</p><h3 id="me-wow-awesome-that-was-literally-just-you-being-at-the-right-place-at-the-right-time-and-offering-value-so-what-happened-next">Me: Wow, awesome. That was literally just you being at the right place at the right time and offering value. So, what happened next?</h3><p><strong>Cynthia: </strong>So covid came, and I went back home to my parents' house. I started writing on Upwork. The day I made my first $40, I felt like a million bucks. While doing this, I was still learning flutter and tweeting about what I was learning. Then someday, a guy reaches out to me. He's like, "Hey, we're looking for a junior flutter developer to join us for a 3-month contract". That was how I got my first dev job.</p><p>Now, something interesting happened afterwards. I didn't want to stay jobless, so I started looking for jobs — anything at all. Someone referred me to this particular job (flutter dev too). After working throughout December —even on Christmas day — I was paid N15,340.</p><h3 id="me-huh-n15-340">Me: Huh? N15,340?</h3><p><strong>Cynthia:</strong> Yeah, so I quit the job and took LinkedIn seriously. I revamped my profile and started putting out content regularly. Content on anything could be on how I was feeling that day or my hot take on a trending topic. It paid off, and my LinkedIn page started growing. Then one day, somebody reached out to me like, "Hey Cynthia, my company is looking for a Technical Writer, and I'd like you to apply". That was how I joined Sterling Bank. Last quarter of 2021, The @ company reached out too, and that was how I joined them.</p><h3 id="me-wow-that-s-one-hell-of-a-story-like-companies-are-the-ones-who-reach-out-to-you-must-be-nice-">Me: Wow, that's one hell of a story. Like, companies are the ones who reach out to you. Must be nice.</h3><p><strong>Cynthia:</strong> Really, my reality is a consolidation of all the experiences I've had in the past. So when people compliment my writing now, it's because I've had enough practice.</p><h3 id="me-so-let-s-go-back-a-bit-you-mentioned-writing-on-upwork-for-someone-who-wants-to-try-to-get-gigs-on-upwork-what-are-things-they-can-do-to-better-position-themselves">Me: So, let's go back a bit. You mentioned writing on Upwork. For someone who wants to try to get gigs on Upwork, what are things they can do to better position themselves?</h3><p><strong>Cynthia: </strong>Getting your first job on Upwork is hard, so I'll advise starting with the lower-priced gigs. The thing is, people will only give you jobs when you already have something to show — like reviews. My first gig was for $5. I didn't mind because the client gave me a 5-star rating and a good review after that gig. Afterwards, it was a bit easier to get slightly better-paying gigs because I had been vouched for via the review I received.</p><p>Another tip is to bring your bio down to a niche. On Upwork, employers are looking for very specific things like API Documentation, Technical Content Strategist, e.t.c. Don't just put 'Writer' on your profile.</p><p>My last tip is to make sure that the first two lines of your proposals are catchy. This is because of the layout of the Upwork employer dashboard. So employers see all applicants' proposals in a vertically card stacked layout. Each card has the freelancer's name, their title, and the first two lines of their proposals. If the employer likes what they see, they'll expand the card. Sometimes, they'll ask applicants to put certain keywords as the first word in their proposals in the job ad. They know most people don't read job ads thoroughly. So that becomes a vetting criterion.</p><h3 id="me-right-let-s-talk-about-interviewing-what-tips-can-you-give-someone-preparing-for-a-technical-writer-interview-based-on-your-interviewing-experience">Me: Right. Let's talk about interviewing. What tips can you give someone preparing for a technical writer interview based on your interviewing experience?</h3><p><strong>Cynthia: </strong>So, for Sterling, I was asked how much I knew about what I would be doing in the role. Before the interview day, I had done my own research about what technical writing within the confines of such an entity meant. It was all about internal documentation, recording processes and features, and so on. So when I was asked how much I knew about writing API docs, I told them that while I do not have experience writing API docs, I've used API's before, I knew how they work, so it wouldn't be difficult for me to learn how to document them. I learned on the job using Stripe, PayStack, and Flutterwave documentation as inspirations.</p><p>So, I'd say do your research, sell your strengths, and showcase willingness to learn.</p><p>For my second job in the @ company, the interview was in 3 stages. The first one was with the person that reached out to me alongside two other people. It was more of chitchat and getting to know me better. The second one was with the people who worked in marketing, social media, and QA. It was a chat too. The third stage, which was more difficult, was the three co-founders. Midway, they asked me what the last thing I wrote was, and I sent them an <a href="https://likeamfive.tech/non-fungible-tokens-nfts">NFT article</a> I wrote on my blog. They liked the article so much that they offered me the job on the spot. Meanwhile, they said that they'd get back to me in a few days with their verdict before that.</p><p>So, my next tip would be to always to be learning and have sample articles that you can show. Like a technical writing portfolio.</p><h3 id="me-thanks-for-my-last-question-what-advice-would-you-give-to-someone-trying-to-break-into-technical-writing">Me: Thanks. For my last question, what advice would you give to someone trying to break into technical writing?</h3><p><strong>Cynthia:</strong> First advice would be: if you're from a non-technical background, take an introduction to programming course, or get a programming for dummies book. You'll be working in the software development ecosystem, so it's important that you know how they work.</p><p>Next is to create a blog using something like Hashnode and start writing. Write about things you're learning. If you're from technical background then just start writing. You get better at writing by writing. And also opportunities can find you while you're doing that. For instance, that NFT article I wrote got me a discord moderator gig.</p><h3 id="me-nice-one-now-before-i-let-you-go-based-on-all-the-experiences-you-ve-had-what-s-your-biggest-life-lesson-or-a-mantra-that-you-live-by">Me: Nice one. Now before I let you go, based on all the experiences you've had, what's your biggest life lesson or a mantra that you live by?</h3><p><strong>Cynthia:</strong> That would be: <em>Be willing to learn. Be willing to test yourself. Be willing to go beyond what you know. Evolve</em>.</p><p>You can connect with Cynthia on <a href="https://twitter.com/iamCynthiaPeter">Twitter</a> and checkout <a href="https://cynthiapeter.com/">her blog</a>.</p>]]></content:encoded></item><item><title><![CDATA[TCCS #1: What is Content Design with Amy Burns]]></title><description><![CDATA[Amy Burns is a Senior Content Designer at GitHub. In this interview, she talks about her career, and what she does as a content designer.]]></description><link>https://www.everythingtechnicalwriting.com/content-design-with-amy-burns/</link><guid isPermaLink="false">Ghost__Post__62138ecb66274a001db921e0</guid><category><![CDATA[Interviews]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Fri, 07 Jan 2022 08:25:57 GMT</pubDate><content:encoded><![CDATA[<h1/><blockquote>The Tech Content Creator Series is a monthly interview series in which I interview people in technical content creation roles (i.e. technical writers, documentation engineers, developer advocates, and what have you) about their careers. The goal is to inspire, motivate, and hopefully impact you.</blockquote><p><br>Amy Burns is a Senior Content Designer at GitHub, where she works with the documentation team to make the GitHub docs better for GitHub users. Last month, after she announced her promotion, I sat down with her (virtually, of course) to talk about her journey into tech, her career as a technical writer, her promotion, and what she does as a content designer.</br></p><figure class="kg-card kg-embed-card"><blockquote class="twitter-tweet"><p lang="en" dir="ltr">Finally got that Senior title! I’m now a Senior Content Designer <a href="https://twitter.com/github?ref_src=twsrc%5Etfw">@github</a>, working to make our docs amazing for our users. 💃🎉🎉</p>&mdash; Amy (@timeyoutakeit) <a href="https://twitter.com/timeyoutakeit/status/1466237759018782728?ref_src=twsrc%5Etfw">December 2, 2021</a></blockquote>
<script async="" src="https://platform.twitter.com/widgets.js" charset="utf-8"/>
</figure><h3 id="me-hi-amy-once-again-congratulations-on-your-promotion-that-s-very-massive-"><br><strong>Me:</strong> Hi Amy, once again, congratulations on your promotion. That’s very massive.</br></h3><p><strong>Amy</strong>: Thank you. It was a hard fought for promotion.</p><h3 id="me-so-content-design-haven-t-actually-heard-of-that-before-how-did-you-get-into-the-field"><strong>Me:</strong> So content design? Haven’t actually heard of that before. How did you get into the field?</h3><p><strong>Amy:</strong> Frankly, I didn’t even know content design was a thing a year ago. I’ve been a technical writer since like 2013. Along the way, I found out that what was really of interest to me wasn’t the writing. What I really enjoyed the most was anything that involved finding out what the user actually needed from a piece of content and how to provide that. </p><p>So, a bit of background: I used to work as a technical writer at a startup, Xamarin. The startup was later acquired by Microsoft and I got moved to a P.M role. That role opened me up to a lot of skills like conducting user research. However, I missed doing documentation, so I joined GitHub as a technical writer to work with the documentation team. </p><p>Influenced by my former PM role, I found myself wanting to do user research to understand what users actually needed from the GitHub documentation. As is typical in most organizations, we usually create content from a business standpoint, telling users things like "here's how to make a pull request, here's how to do this". But the question is, is that what the user actually needs to help them get their job done? Is it presented in a way that makes sense to them?”. So, I talked to my manager about what I did enjoy doing and what I did not, and we basically created the content designer role.</p><h3 id="me-wow-awesome-i-love-that-github-is-accommodating-and-flexible-enough-to-allow-employees-to-pursue-their-passions-within-the-org-so-i-think-i-have-a-vague-idea-of-what-content-design-is-but-could-you-please-define-it-in-a-nutshell-for-the-sake-of-our-readers"><strong>Me: </strong>Wow. Awesome. I love that GitHub is accommodating and flexible enough to allow employees to pursue their passions within the org. So, I think I have a vague idea of what content design is, but could you please define it in a nutshell for the sake of our readers?</h3><p><strong>Amy:</strong> I would say content design is the process of creating content that is solely focused on the needs of the intended user. In the tech industry, we frequently create documentation based on assumptions on how we think that the user might need them. There is never any real research done on the actual people who use the documentation. Content design is a shift away from that paradigm, to using user research to find out what users need from your documentation and giving it to them.</p><p>For anyone looking to grasp what content design is, I’d recommend the book <a href="https://amzn.to/3zATJS0" rel="noreferrer nofollow noopener">Content Design by Sarah Richards</a>. In fact, I think it’s a book everyone who creates content should read. It’s very handy. The '<a href="https://abookapart.com/collections/books" rel="noreferrer nofollow noopener">a book apart site</a>' is also a great resource. They publish these short books on design and writing.</p><h3 id="me-so-have-you-always-been-a-technical-writer"><strong>Me: </strong>So, have you always been a technical writer? </h3><p><strong>Amy:</strong> My degree was in computing and IT originally, and I started as a software engineering intern. It’s quite funny, I actually got that job through Twitter.  I know how to program, but it’s not just in my heart. I just don’t have the wherewithal to keep at it. But because I've always been interested in computers and enjoyed working in technology, I knew it was an industry I wanted to stay in. Fortunately, towards the end of my internship, the company opened up a position in the docs team and sort of poached me. It was in that role that I learnt technical writing. You know, back in uni, I never knew that technical writing was an option. I had never heard of it. </p><h3 id="me-do-you-think-that-your-computing-degree-and-your-programming-background-gave-you-an-edge-when-you-switched-to-technical-writing"><strong>Me:</strong> Do you think that your computing degree and your programming background gave you an edge when you switched to technical writing? </h3><p><strong>Amy:</strong> My first reaction would be to say no. However, I think having that knowledge helped me be familiar with code and gave me a foundation. But, I must say, that the most important skill for a technical writer to have is empathy for the user. A lot of the technical writers I know don’t have a technical background. They sort of learnt it over time.</p><h3 id="me-ok-cos-i-get-dms-all-the-time-from-people-asking-me-how-they-can-get-started-with-technical-writing-i-always-advise-them-to-start-with-taking-an-introductory-computing-course-because-i-feel-that-knowledge-is-essential-to-gain-some-foundation-"><strong>Me:</strong> Ok. Cos, I get dms all the time from people asking me how they can get started with technical writing. I always advise them to start with taking an introductory computing course, because I feel that knowledge is essential to gain some foundation.</h3><p><strong>Amy:</strong> Yes, I totally agree, and I think that ultimately if someone does not have the background but is willing to learn, then it’s doable. </p><h3 id="me-so-say-someone-wants-to-pursue-a-technical-writing-career-what-advice-and-tips-can-you-share-based-on-your-experience"><strong>Me:</strong> So, say someone wants to <a href="https://everythingtechnicalwriting.com/everything-you-need-to-know-about-technical-writing/" rel="noreferrer nofollow noopener">pursue a technical writing career</a>. What advice and tips can you share based on your experience?</h3><p><strong>Amy:</strong> I think Twitter (I have to come back to this, cos it's pretty awesome), and sharing any piece of writing that they’re working within their network. Another way is open source. You can <a href="https://everythingtechnicalwriting.com/everything-you-need-to-know-about-technical-writing/#:~:text=on%20this%20list.-,How%20to%20build%20a%20technical%20writing%20portfolio,-When%20you%20want" rel="noreferrer nofollow noopener">build up a technical writing portfolio</a> through contributing to open source docs like GitHub, Microsoft. Most recruiters are going to be looking at your profile to see some contributions. So that’s a great base. Start with small issues and build up. </p><p>Another important thing to have is empathy. It will help you be in touch with your users and be able to create quality content for them. Ultimately, that’s what we do this for. We’ve all read bad documentation, and the experience is never nice. </p><h3 id="me-hahaha-aws-comes-to-mind-"><strong>Me:</strong> Hahaha. AWS comes to mind. </h3><p><strong>Amy:</strong> It's funny you say that because I used to work in iOS development. Despite all the good things Apple does, they do a poor job with documentation. So, in my time at Xamarin, I told myself that this was something I was going to make a difference in. </p><p>In our Xamarin docs, a lot of our users were like having to provision iOS devices. So, I basically overhauled that section of Apple docs focusing on devs what coming to the docs for the first time wanted to see. The rewrite had so much impact on our users. I still think it’s one of the best writing I’ve ever done. We even found out that iOS developers, who didn’t actually use Xamarin, were using our docs because it was much better than Apple’s. </p><p>This brings me to the fact that companies should prioritize documentation. Some companies hire a million developers and then hire one docs person. So, they eventually end up with poor documentation. They forget that everyone whose going to use their product will come to the docs.</p><p>And I think that’s why what you’re doing with this platform is very important: educating people about technical writing as a viable career option. We need more creative and smart people who care a lot about the end users; people who can think of new ways to present content.  </p><p>Connect with Amy on <a href="https://www.linkedin.com/in/amy-amy/">LinkedIn</a>, or <a href="https://twitter.com/timeyoutakeit">Twitter</a>.</p>]]></content:encoded></item><item><title><![CDATA[The technical writing process: How to do technical writing like a pro]]></title><description><![CDATA[Technical writing can be difficult, especially when you're writing about something new and unfamiliar. However, following a writing process makes it a lot easier.]]></description><link>https://www.everythingtechnicalwriting.com/the-technical-writing-process/</link><guid isPermaLink="false">Ghost__Post__62138ecb66274a001db921df</guid><category><![CDATA[Introductory]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Mon, 20 Dec 2021 10:30:42 GMT</pubDate><content:encoded><![CDATA[<p>If I had a dollar for every time someone has asked me, "I am not a natural-born writer, how can I get better at technical writing?", I'd probably own a private jet.</p><p>My answer is to follow a technical writing process.</p><p><a href="https://everythingtechnicalwriting.com/everything-you-need-to-know-about-technical-writing/">Technical writing</a> — just like every other creative process — is difficult, especially when you're writing about something new and unfamiliar (which is probably what you'll be doing most of the time as a technical writer). Even 'natural born' writers will struggle without a writing process.</p><p>A writing process breaks the intimidating task of "TECHNICAL WRITING" into distinct steps that you can check off one by one to encourage the creation of content in a systematic way.</p><p>Good writing requires planning and preparation. Based on my experience creating technical content (technical articles and documentation) for some startups, I'll share the same process I follow to write high-quality technical content consistently. This will help you overcome the initial blank-page confusion, so you can also start writing better technical content (whether in a personal or professional setting) with speed and ease.</p><ol><li>Define your audience</li><li>Define the goal of the content</li><li>Write an outline</li><li>Do your research</li><li>Write the first draft</li><li>Rewrite the first draft</li><li>Fine-tune and polish</li><li>Ask for feedback</li><li>Publish and share</li></ol><p><em>N.B: This technical writing process article does not cover how to generate topic ideas or decide what to write. It assumes that have what to write about. It also does not place much emphasis on grammar rules because they are secondary. Instead, it focuses on a series of high-level steps that you can follow to give direction and purpose to your writing and make the task less daunting.</em></p><h2 id="stage-1-of-the-technical-writing-process-prewriting">Stage 1 of the technical writing process: Prewriting</h2><p>Prewriting refers to everything you do before writing an actual draft. Prewriting is the stage in the technical writing process in which you define the direction and strategy for the content you're about to write.</p><p>Do these prewriting tasks well, and writing the draft will be a breeze.</p><h3 id="1-define-your-audience">1. Define your audience</h3><p>To create effective content (i.e, content that will be useful to your audience), you need to understand who they are. When you understand your audience, you'd be able to write content that resonates with, impacts, and offers them a better reading experience.</p><p>To define your audience, ask yourself: <em>Who am I writing this piece of content for? Are they beginner developers, mid-level developers, product managers, designers, etc?</em></p><p>Your intended audience determines the tone you should lean on while writing, the level of background information you need to provide, the frequency with which you define terminology, what you should cover and shouldn't, and the overall direction of the content.</p><p>For example, say you're writing an article on how to build a demo CRM with <a href="https://reactjs.org/">React</a>, which will require connecting a database (SQL or otherwise). If your intended audience are frontend developers with no idea of databases or SQL, you'll need to have a section introducing them to the basics of SQL databases and how they work, and maybe a link to go read up on SQL commands. </p><p>However, if your audience are core back-end developers, you'll need to have a section introducing them to React and how it works.</p><h3 id="2-define-the-goal-of-your-technical-content">2. Define the goal of your technical content</h3><p>Every piece of content you write should have a goal; otherwise, you'll write something that doesn't deliver any value because your points will be all over the place. Just like defining your audience, defining the goal of every piece of content helps provide you with more direction and focus.</p><p>The goal of every piece of content can be thought of in two parts: the producer's goal and the readers' goal.</p><p><strong>The producer's goal</strong></p><p>A producer is someone or a group of persons who wants to write a piece of content. In this case, the producer is you (an individual technical writer writing for yourself, or the company paying for you).</p><p>Defining the producer's goal helps you understand why you or your company has decided to write a particular piece of content. Without specifying this goal, you're less likely to care about what you're writing. And, when you don't care about what you're writing, you're less likely to deliver value.</p><p>To define your producer goals, ask yourself these questions:</p><ul><li><em>"As a person, why do I want to write this piece of content?"</em></li><li><em>"As a company, why should we produce this piece of content?"</em></li></ul><p>An example of a producer's goal could be:</p><ul><li>"<em>I am writing this article to showcase my understanding of a particular subject matter and encourage people to sign up to my newsletter or follow me on Twitter</em>" (personal)</li><li>"<em>We're creating this piece of content to drive more awareness for our product and encourage people to use it or download it</em>" (company)</li></ul><p><strong>The readers' goal</strong></p><p><strong> </strong>The readers' goal is why your audience should care about your content or even read it. When users search for content, their goal is usually to either get a solution to a pain point or find answers to a pressing question.</p><p>To understand your readers' goal, ask yourself:</p><ul><li><em>"What are the pain points of my target audience regarding this particular topic?",</em></li><li><em>"Regarding this particular topic, what are the pressing questions that my audience are looking for answers to?"</em></li></ul><p>As much as your goals are important, that of your audience is more important. It is only when you create value for your audience that they will convert (i.e help you achieve your own goal). So, you need to marry your goals to that of your audience, to achieve better results.</p><p>For example, the producer's goals arrived at in the preceding section can be reframed to these below, which puts the reader into consideration:</p><ul><li><em>"Frontend developers struggle with understanding the concept of React context. I will use the analogy of driving a car to break down the concept and make it more relatable. This will showcase my deep understanding of the concept, and then I will encourage readers to sign up for my newsletter for similar content."</em></li><li><em>"Setting up public APIs is always a tedious task for developers because of the numerous steps involved. This piece of content will show developers how they can use our product to set up public APIs in just 3 steps. This should encourage them to start using it"</em></li></ul><p>After you arrive at the combined goal, write it down. That way, you'll be able to cross-check your writing with it, in the end, to confirm that you were able to deliver on your goal.</p><h3 id="3-write-an-outline">3. Write an outline</h3><p>An outline is like a map that guides you to a destination — without which you'll end up missing your way.</p><p>An outline can be described as the barebones structure of your content. It allows you to narrow down your ideas to the main points that you need to cover, ensuring that you deliver on the goal of that specific piece of content without deviating.</p><p>An outline typically contains:</p><ul><li>A title</li><li>A thesis (the primary point of the article), and</li><li>Headings and sub-headings representing the points you'll need to cover to deliver on your content goal.</li></ul><p><strong>How to come up with a title for your technical documents</strong></p><p>Every piece of content should have a title that summarizes it's value proposition.</p><p>Most of the time, I use the template below to generate article or documentation titles:</p><p>[goal or end result] for [target audience].</p><p>For example, 'How to Set Up Public APIs in 3 Easy Steps for Developers Who Hate Stress'. Anyone who sees the title will immediately understand what they're getting and who it's written for. This makes it easier for your target audience to identify with your content, among others.</p><p><strong>How to come up with a thesis for your technical documents</strong></p><p>After defining the title, define the thesis or the main point of the content. The thesis is the main message that a piece of content attempts to convey, and it is usually closely related to the goal you defined in the previous section.</p><p>For example, following the public API article example, the thesis could be:</p><p><em>"No developer should be subjected to spending an ungodly amount of hours setting up public APIs. Our tool makes setting up public APIs as easy as three lines of code, so developers can channel that time to do more impactful work".</em></p><p><strong>How to establish headings and points to guide the structure of your technical documents</strong></p><p>After you've defined your thesis and content goal, the next thing is to construct the body's structure.</p><p>Consider all the significant points you'll need to cover to deliver on both your content goal and on your thesis. Then, write them down as headers.</p><p>If the goal is to explain a technical concept, list all of the components that comprise that concept. If it is a step-by-step guide for completing a specific task, list all necessary steps. Then, under each major heading, fill in the sub-points or sub-tasks that you'll need to address as well.</p><p>For example, my outline for this article could look like so:</p><figure class="kg-card kg-image-card"><img src="https://res-2.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Screenshot-2021-12-15-at-07.18.18.png" class="kg-image" alt="" loading="lazy" width="1466" height="1306"/></figure><h3 id="4-do-your-research">4. Do your research</h3><p>Research is a vital step in writing. So crucial that I'd like to say that a successful piece of writing depends on 60% research, 10% writing, 10% editing, and 20% distribution.</p><p>Research is a continuous process when writing. From the moment you decide what to write on, to defining your target audience, to drawing up an outline, you must conduct research to gain perspective. The level of research you do will reflect on how confident you'll feel about writing that particular piece of content.</p><p>So after you've drawn up an outline, do some research and read up on existing similar or related content to gain more understanding and authority over the topic. If you need to build out a demo app or write some code, this would also be a good time to do that.</p><h2 id="stage-2-of-the-technical-writing-process-time-to-write">Stage 2 of the technical writing process: Time to write</h2><p>After defining the basic structure and direction and reading up on helpful information, it's time to start writing.</p><h3 id="1-write-the-first-draft-">1. Write the first draft.</h3><p>The goal of the first draft is to help you get all of the ideas in your head onto paper (within the constraints of your outline and target audience, of course). Write down all of the ideas that come to you in relation to your outline. It doesn't have to look good or even be moderately ready for publishing. Write, then fix later.</p><p>While writing out this draft, you may likely get stuck on some areas. That's perfectly normal. This might indicate that you need to stop and go do more research or consult someone knowledgeable about the topic. Alternatively, mark the section that needs to be worked on as Todo and continue writing the sections that you flow freely to you.</p><h3 id="2-rewrite-the-first-draft">2. Rewrite the first draft</h3><p>The goal of this rewrite is to organize all of the ideas that were jumbled together in your first draft into a coherent and presentable format.</p><p>In this phase, you should arrange paragraphs and sentences one after the other to achieve flow and remove any awkward phrases or duplicate information. It would help if you also wrote a proper intro and outro.</p><p>Your intro should answer the question: "Will this help me?, Should I be reading this?". It needs to contain the goal of the content (what the user will learn from the content), and any prerequisites knowledge they need to have.</p><p>In contrast, your outro should include the next steps for the reader (what should they do next after reading your article). This can include anything from relevant links to additional resources.</p><p>Asides that, here's a list of other things to do in the rewrite phase:</p><ul><li>Rewrite every paragraph and section with the key ideas positioned first, <a href="https://everythingtechnicalwriting.com/create-content-that-people-will-read/#:~:text=2.%20Make%20your%20content%20scannable%3B%20People%20scan%20before%20they%20settle">to promote readability</a>.</li><li>Remove anything that doesn't support your main point or will distract from key points.</li><li>Verify that there are no gaps in your writing and that you've provided all the information the reader needs to arrive at the goal set out at the beginning.</li></ul><p>Typically I'd say put some distance between your first draft and every rewrite. If you can afford the luxury of time, the next day is best. This allows you to have a fresh perspective and brain.</p><h3 id="3-fine-tune-and-polish">3. Fine-tune and polish</h3><p>Now, this is the stage where you read through your more polished writing sentence by sentence and try to clean it up even more. Unlike the rewriting, which is more concerned with high-level coherence, this phase is about minute tweaks.</p><p>Here's a checklist of some things to do at this stage:</p><ul><li>Remove awkward phrases or ambiguous words that may make it hard for the reader to understand the content.</li><li>Make sure all links work</li><li>Create smooth transitions between paragraphs and sentences.</li><li>Run content through a grammar checker like <a href="https://app.grammarly.com/">Grammarly</a></li><li>Run a plagiarism check using a tool like Grammarly or <a href="https://unicheck.com/">Unicheck</a>.</li><li>Break down longer sentences of more than 25 words into two.</li><li>Break paragraphs into a maximum span of 6 lines.</li><li>Clean out your subheaders. Make them as brief and as clear as possible.</li></ul><h2 id="stage-3-of-the-technical-writing-process-after-writing-">Stage 3 of the technical writing process: After writing…</h2><p>Now that you're done with writing, it's time to ask for feedback and get it ready for publishing.</p><h3 id="1-ask-for-feedback">1. Ask for feedback</h3><p>You can either stop at the fine-tuning stage and move on to the publishing phase, or ask for feedback from an extra pair of eyes (like a friend) if you're writing for yourself.</p><p>If you're working in a professional setting, you'd usually send this to your clients or superiors for feedback and then try to incorporate their suggestions.</p><h3 id="2-publish-and-share">2. Publish and share</h3><p>After you've incorporated feedback, it's now time to publish. You'd typically transfer the content from your drafting location (google doc, dropbox, e.t.c) to the publishing medium (code editor, markdown files, CMS). Then share the excellent content you've written to social media so other people can see it.</p><p>What's the essence of writing if no one ever sees it?</p><p>Take care not to get stuck on the editing and polishing loop. The thing about technical writing is that there will always be room for more tweaking, some more editing, or something you can do to make it better. But do that, and you'll never finish.</p><p>As Leonardo da Vinci said: "<em>Art is never finished but abandoned</em>". Set a deadline, stick to it, and consider it done.</p><h2 id="good-writing-is-a-skill-and-can-be-developed">Good writing is a skill and can be developed</h2><p>Writing well is a skill that can be honed with enough practice and time. I hope the technical writing process discussed above has provided you with a framework to get better at technical writing. However, consider it merely a suggestion. You're free to tweak it and rearrange it as you see fit until you find something that works for you. There is no "right way" or "wrong way" to write, but having a defined technical writing process makes it easier.12.1 3</p>]]></content:encoded></item><item><title><![CDATA[Everything you need to know about technical writing]]></title><description><![CDATA[Technical Writing is a viable career path in the software ecosystem, with an average pay range of $45k to $105k. In this article, you'll learn what you need to become a technical writer.]]></description><link>https://www.everythingtechnicalwriting.com/everything-you-need-to-know-about-technical-writing/</link><guid isPermaLink="false">Ghost__Post__62138ecb66274a001db921dd</guid><category><![CDATA[Introductory]]></category><dc:creator><![CDATA[Linda Ikechukwu]]></dc:creator><pubDate>Thu, 21 Oct 2021 08:48:17 GMT</pubDate><content:encoded><![CDATA[<p>When most people consider possible career paths in tech, they automatically think of paths such as frontend development, backend development, UI/UX design, product management, and so on. Rarely, does anyone ever think of technical writing.</p><p>Yet, according to Glassdoor, technical writing is a very lucrative career path, with an average pay range of $45k to $105k. As a matter of fact, the employment of technical writers is expected to rise at a <a href="https://www.bls.gov/ooh/media-and-communication/technical-writers.htm">rate of 12%</a> between 2020 and 2030 — higher than the average for all occupations.</p><p>Following a <a href="https://twitter.com/_MsLinda/status/1389893412669820929?s=20">tweet</a> I posted on how to make money as a freelance technical content writer, numerous people messaged me to ask questions like: "what is technical writing?", "how can I become a technical writer?", "what do I need to know to become a technical writer?" and "how can I get a job as a technical writer?".</p><p>After much procrastination, I decided to write this article to answer some of those questions. In this article, you will learn:</p><ul><li>What is technical writing?</li><li>Who is a technical writer?</li><li>What skills do you need to become a technical writer?</li><li>Technical writing courses (free &amp; paid)</li><li>How to build a technical writing portfolio</li><li>Possible technical writing career paths</li><li>List of technical writing communities and job boards</li></ul><h2 id="what-is-technical-writing">What is technical writing?</h2><p>Technical writing is any form of writing directed at a specific audience that explains complex technical concepts in simple terms. </p><p>While technical writing applies to various industries, this article's focus is on what technical writing entails specifically in the software development ecosystem.</p><p>In the context of software development, technical writing is a type of writing that explains how a software product, concept, technology, or process works. It could be in the form of API documentation, tutorials, how-to guides, or conceptual guides.</p><p>If you want to work in tech but don't want to write code full-time and enjoy creating written content to educate others, technical writing could be a good career path for you.</p><h2 id="who-is-a-technical-writer">Who is a technical writer?</h2><p>A technical writer serves as a link between a piece of software and the people who will use it. As a technical writer, your work will revolve around creating content for two audience categories: internal users and external users. Depending on your job description, you may be creating content for one or both of these audiences.</p><p>Internal users are developers within an organization. Every software development team has APIs, systems, tools or processes that they make use of to build stuff. As a technical writer, your job may be to create internal documentation and wikis that will serve as a knowledge base for how these APIs, systems, and processes work.</p><p>External users are people who make use of an organization's software service or product. These users may sometimes be developers from other organizations. As a technical writer, your job may be to create external documentation, how-to guides, FAQs, tutorials or concept articles, that introduce these users to what your organization's product or service is all about and how it works.</p><h2 id="what-skills-do-you-need-to-become-a-technical-writer">What skills do you need to become a technical writer?</h2><p>In my opinion, to be an excellent technical writer, you need to have three core skills:</p><h3 id="good-writing-skills">Good writing skills</h3><p>Quite obvious for a technical "writer" role, yeah? As a technical writer, you should be able to string words together to produce meaningful, concise content that adequately communicates the topic or subject at hand.</p><p>Luckily, even if you weren't born a writer, writing can be learned and developed. You can improve your writing skills by taking a course on writing, practising, and reading what has been done by others to develop your vocabulary and creativity.</p><h3 id="fast-learning-and-research-abilities">Fast learning and research abilities</h3><p>As a technical writer, you'll often be required to write about topics you have no prior experience with. As a result, you should be able to carry out research when necessary to fully comprehend a subject and still write about it concisely, within a stipulated amount of time.</p><h3 id="software-development-knowledge">Software development knowledge</h3><p>There is no "traditional" academic work required to become a technical writer. However, knowledge or experience writing code in any niche (frontend, backend, or mobile) or language (JavaScript, PHP, Python, Ruby, et cetera) will give you an advantage.</p><p>Most people like to argue that this is not important, but I disagree. As a technical writer, you'll often be required to create content that clarifies how a programming concept or a piece of code works. Even if you'll be working with a different set of languages, tools, or technologies than what you're used to, some experience of how one programming language or one tooling works, will help you learn another faster.</p><p>Also, since your primary audience will most likely be developers, having some software development knowledge will help you be more familiar with developer speak, and be better positioned to communicate with them.</p><p>So, consider taking an introduction to computer science/programming course.</p><blockquote>In summary, as a technical writer, you need to be able to write clearly, interpret code, and learn about tricky technical concepts through a combination of independent research and asking questions.</blockquote><p>For further proof, here's what a typical technical writer job requirement from <a href="https://www.flutterwave.com">Flutterwave</a> looks like:</p><figure class="kg-card kg-image-card"><img src="https://res-1.cloudinary.com/hifirsa5v/image/upload/q_auto/v1/ghost-blog-images/Screenshot-2024-03-19-at-14.29.22.png" class="kg-image" alt="Technical writer job description from flutterwave" loading="lazy" width="728" height="643"/></figure><h2 id="recommend-technical-writing-courses-free-and-paid-">Recommend technical writing courses (free and paid)</h2><p>As a newbie, I'd recommend taking an introductory course on technical writing to help you gain the guided knowledge you'll need to kick-start your journey.</p><p>Here are some courses you can check out:</p><ul><li><a href="https://technicalwriter.teachable.com/p/home?referral_code=6TJ7SI">Technical writing course by TechnicalWriterHQ</a> (paid)</li><li><a href="https://www.ed2go.com/courses/writing/writing-and-editing/ilc/fundamentals-of-technical-writing">Fundamentals of Technical Writing by Ed2go</a> (paid)</li><li><a href="https://developers.google.com/tech-writing">Technical writing course by Google</a> (free)</li><li><a href="https://philipkiely.gumroad.com/l/uZPZU">Writing for Software developers</a> (paid)</li><li><a href="https://alg.manifoldapp.org/projects/open-tc">Open technical communication course</a> (free)</li><li><a href="https://app.pluralsight.com/library/courses/technical-writing-software-documentation/table-of-contents">Technical writing: Documentation on software projects by Pluralsight</a> (paid)</li></ul><p>Also, if you have no software development experience, then you should consider taking an introduction to programming course. Here are some: </p><ul><li><a href="https://www.udacity.com/course/intro-to-programming-nanodegree--nd000?irclickid=RX2QSCyo5xyITg8RYKW662mZUkG38fwtJy0C3g0&amp;irgwc=1&amp;utm_source=affiliate&amp;utm_medium=&amp;aff=3074044&amp;utm_term=&amp;utm_campaign=__&amp;utm_content=&amp;adid=788200">Udacity Introduction to Programming</a> (paid)</li><li><a href="https://www.edx.org/course/introduction-computer-science-harvardx-cs50x">Edx Introduction to Computer Science</a> (free)</li></ul><h2 id="how-to-build-a-technical-writing-portfolio">How to build a technical writing portfolio</h2><p>When applying for a technical writer role (or any of the other related roles above), you'll most likely be asked to provide links to your writing samples or technical writing portfolio.</p><p>A technical writing portfolio is a document that contains a list of all of your technical writing samples. Its purpose is to demonstrate to prospective employers or interviewers that you are capable of and have experience writing about technical topics or concepts.</p><p>As a newbie, having one document that links to all your stellar public technical writing samples that you can show prospective employers will always tip the scale in your favour. It certainly has for me severally. I have articles published on my <a href="https://www.codewithlinda.com/blog/">personal site</a>, <a href="https://blog.logrocket.com/author/lindaikechukwu/">Logrocket</a>, <a href="https://css-tricks.com/author/lindaikechukwu/">CSS Tricks</a>, <a href="https://www.freecodecamp.org/news/author/linda/">freeCodeCamp</a>, <a href="https://bitmovin.com/author/linda-i_draft-dev/">Bitmovin</a>, <a href="https://statushero.com/blog/comparing-scrum-kanban-lean/">StatusHero</a>, <a href="https://www.backhub.co/blog/author/linda-ikechukwu">Backhub</a>, <a href="https://fingerprintjs.com/blog/permanently-ban-users/">FingerPrintJS</a>, and a host of other sites.</p><p>You can start by creating articles about software development related concepts from whatever introduction to computer science/programming course you decide to take. Then publish these articles either on your own blog or on developer-focused blogging platforms like <a href="https://dev.to/">dev.to</a>, <a href="https://hashnode.com/">hashnode</a>, or <a href="https://hackernoon.com/">hackernoon</a>.</p><p>If you're more interested in documentation, you can get some documentation experience by contributing to documentation for open-source projects. Here's a <a href="https://amrutaranade.com/2018/03/21/list-of-open-source-projects-that-accept-docs-contributions/">list</a> of open-source projects with documentation opportunities to start from, and a <a href="https://opensource.guide/how-to-contribute/">guide</a> on how to contribute to open-source projects. You can also get documentation experience through programs like <a href="https://developers.google.com/season-of-docs">Google season of Docs </a>or <a href="https://www.outreachy.org/">Outreachy Internships</a>.</p><h2 id="possible-technical-writing-career-paths">Possible technical writing career paths</h2><p>Asides from the explicit job title of "Technical Writer", strong technical writing skills can also help you land roles like:</p><ul><li><strong>Developer educator/ Developer advocate</strong>: These people are usually tasked with creating documentation, tutorials featuring sample code examples and sample repositories, blog content, and sometimes video content to ensure that users have all the information they need to succeed with a product.</li><li><strong>Technical Documentation Officer</strong>: These people are solely focused on creating documentation. This could either be internal facing documentation or external-facing documentation.</li><li><strong>Technical Content Writer/ Developer Marketer</strong>: These people typically work with the marketing team of an organization to create articles aimed at stimulating interest in its software products or services within a target audience.</li></ul><p>You can also work as a freelance technical writer for some organizational community blogs, or technical content marketing agencies like the ones on <a href="https://github.com/malgamves/CommunityWriterPrograms">this list</a>.</p><h2 id="list-of-technical-writing-communities-and-job-boards">List of technical writing communities and job boards</h2><p>The importance of communities cannot be overemphasized. Being a member of a community of like-minded people will help you grow, expand your network, and be introduced to different opportunities.</p><p>So, as my final act, here is a list of technical writing communities that you can join:</p><ul><li><a href="https://www.facebook.com/groups/564986683562634/">Technical Writers United </a>(a Facebook group)</li><li><a href="https://writethedocs.slack.com">Write the docs</a> (Slack channel)</li><li><a href="https://www.linkedin.com/groups/13705342/">Technical Writing Community</a> (group on LinkedIn)</li></ul><p>Also, here are some job boards where you can find job listings for technical writer roles and other related roles :</p><ul><li><a href="https://jobs.writethedocs.org/">Write the Docs Job Board</a></li><li><a href="https://technicalwriterhq.com/technical-writing-jobs/remote-technical-writing-jobs/">TechnicalWriterHQ Job Board</a></li><li><a href="https://www.flexjobs.com/remote-jobs/technical-writing">Flexjobs</a></li><li><a href="https://www.ziprecruiter.com/Jobs/Technical-Writer">Ziprecruiter</a></li><li><a href="https://www.devrelx.com/jobs">DevRel Jobs</a></li><li><a href="https://startup.jobs/?query=developer%20advocate">Startup Jobs</a></li></ul><h2 id="take-a-leap-into-technical-writing">Take a leap into technical writing</h2><p>In this article, I've discussed the most important points you need to know about technical writing and what it takes to become a technical writer. If you want to delve into the word of technical writing, the first thing I'd advise you to do is to take a course on technical writing. You can start with the courses that I listed above. All the best!</p>]]></content:encoded></item></channel></rss>