They say you’ll not be needed in the future. As a technical writer, I do not take any offence because I know how AI works and why it can’t replace me anytime soon. Only thing it’ll do is to make it easier on me.
It’s one of the most feared misconceptions across documentation teams and corporate workflows.
The panic comes from seeing content tools become smarter every year. But most of that fear isn’t grounded in the actual data.
Among writers specifically, adoption is also high. Surveys show that 61% of writing professionals already use AI tools regularly. With a significant portion incorporating them into their daily workflows.
In this article, we’ll see how AI supports, not replaces, technical writers in 2026. And how you can leverage this shift to become even more indispensable.
The misconception about AI replacing writers
The idea that AI will replace technical writers comes from a surface-level understanding of what AI and technical writing are.
People see AI generating paragraphs, documents, and even full manuals in seconds, and they assume the human role is no longer needed. But that assumption ignores how technical writing works in the real world.
Technical writing is not just about producing text. It’s about:
Understanding complex systems
Asking the right questions
Interpreting incomplete information and translating that into clear guidance for a specific audience.
AI does not understand a product, a system, or a user the way a human does. It predicts language based on patterns. That’s it.
For example, you go through a park every day. Out of 10 times, you saw a dog there around 9 times. So, if I ask you, what will you see there if you go through that park?
Your simple answer will be, “a dog.” That’s because you have data in favor of that.
Now see, AI has gone through that park hundreds of thousands of times. It has much more data available to answer that particular question.
Similarly, AI has data about products all over the world. So it writes quickly.
But it will not be able to find much data for a new product. Then a human writer will be needed again.
Simple as that!
How AI supports technical writers
Once you get the fear of replacement out of your mind, you see AI as an assistant.
It handles the repetitive, time-consuming parts of the job so writers can focus on accuracy, clarity, and decision-making.
1. Improving efficiency without sacrificing quality
Improving efficiency is one of the biggest ways AI supports technical writers.
Technical writing often involves:
Repetitive sections
Similar explanations
Release notes
Documentation updates that follow an existing structure.
Writing all of this from scratch every time is slow and mentally draining. This is where AI becomes useful, not as a replacement.
A sentence rewriter, like sentencerewriter.net, helps technical writers clean up rough drafts or existing documentation. So instead of rewriting the same explanation again and again, it helps restructure sentences and remove unnecessary repetition.
The key point here is intent. The writer already knows what needs to be communicated. The tool simply helps express it more clearly and faster.
And you can always check your writing quality with the Hemingway App. It helps writers identify long sentences, passive voice, and areas where clarity can be improved.
When used together, these tools help technical writers work smarter.
2. Improving consistency across documents
Let me tell you, as a technical writer, consistency is hard to keep, especially when documentation grows over time. Because of:
Multiple writers
Frequent updates
Product changes
Tight deadlines.
They often lead to small variations in your tone, terminology, and sentence structure. These issues seem nothing, but together they can make documentation feel confusing.
This is where an AI reworder, like rewording-tool.com, becomes genuinely useful. Instead of rewriting entire sections manually, writers can use it to standardize explanations across different documents.
Therefore, if the same feature is described in a user guide, a help article, and release notes, the tool helps align phrasing while keeping the meaning intact.
You still decide what is correct. The tool simply helps apply that decision consistently.
3. Assisting with research and technical references
Research is another area where we writers need AI, especially tools like ChatGPT.
You see, technical writing often starts with gathering scattered information from product notes, internal discussions, legacy documentation, or rough technical inputs. Turning all of that into a structured understanding is our job. That takes time. And this is where ChatGPT becomes useful.
It can:
Summarize large chunks of information
Suggest documentation structures
List possible edge cases
Help frame questions that need clarification from engineers or product teams.
So, instead of starting from a blank page, we get a working framework from the beginning. This speeds up the early stages of documentation.
It also helps when dealing with technical references. We can use ChatGPT to explain concepts in simpler terms or generate example scenarios.
This is especially helpful when a writer is documenting unfamiliar systems and needs a clearer mental model before validating details with subject-matter experts.
4. Supporting multilingual and global documentation
Global products need global documentation. Not everybody speaks English.
And this is another area where AI strongly supports technical writers. Creating the same documentation in multiple languages, tones, and formats is time-consuming when done manually.
A paragraph writer helps by creating content in different languages while adjusting tone and phrasing to match how people actually communicate in that region.
This matters because technical documentation is also about familiarity. The way instructions are given, or steps are explained can vary widely from one region to another.
The paragraph-generator.com helps technical writers adapt content for different audiences without rewriting everything from scratch.
But please use an AI detector at this point as well. It will help you maintain quality across languages. Because working with multilingual content, it’s easy for quality to slip without noticing.
An AI detector helps writers review structure, tone, and naturalness across different languages and formats.
Together, these tools allow technical writers to scale documentation globally without losing control. Your content stays accurate, localized, and readable.
5. Reducing writer’s fatigue and improving focus
Technical writing demands continuous focus. Over time, you can get fatigue, which affects clarity, decision-making, and overall quality.
This is where AI gives you mental relief.
An AI changer tool helps reduce this fatigue by offering alternative ways to express the same idea of yours. So, you don’t start at the same sentence and rewrite it multiple times. The writer can generate different versions instantly. Then you just have to choose the one that fits best.
This process is especially helpful during revisions. When a paragraph feels “almost right” but not quite, a word changer provides fresh phrasing. It breaks mental blocks and helps maintain momentum, which is critical in long-form technical documentation.
By making such small decisions, writers preserve their energy for what truly matters: accuracy, logic, and usability.
Conclusion
The fear that AI will replace technical writers happens to the people who do not understand the system.
Once you realize, you understand that it is not here to remove humans from the process.
When used correctly, AI helps technical writers work more efficiently. None of these tools decides what is correct, useful, or safe. That responsibility still belongs to the writer.
The future of technical writing is not human versus AI. It is human plus AI. And writers who learn to use these tools wisely will not become irrelevant.
TL;DR: Finding qualified technical writers requires strategic sourcing beyond traditional job boards. Most successful hiring processes combine targeted outreach on platforms like Dev.to and Medium with clear evaluation criteria and competitive compensation structures.
Key steps to hire technical writers:
Define requirements: Create detailed briefs, hiring rubrics, and clear expectations before searching
Search strategically: Find writers on Dev.to, Medium, GitHub, and technical communities, not generic job boards
Personalize outreach: Reference specific work, be genuine, and offer clear value beyond just payment
Understand motivations: Technical writers value bylines, distribution, and editorial feedback as much as compensation
Build inbound interest: Create community writing programs and referral systems for sustainable hiring
In the past four years at Draft.dev, we’ve written over 3,800 technical blog posts and worked with over 300 technical writers. In the meantime, we’ve reviewed thousands of applications from technical content writers and reached out to hundreds of others to help us create content for our clients.
Needless to say, I’ve learned a lot about creating technical content at scale, and one of the most fundamental parts of the process is finding great technical writers for hire.
In this post, I’ll share the process we’ve used to find technical writers for hire at Draft.dev. It takes preparation and time but, hopefully, the insights here will help you find the right technical writer faster.
Note: If you get stuck looking for technical writers, set up a call. We’d be happy to help troubleshoot your issues or answer questions about how we work with clients.
How Not to Hire a Technical Writer
For the first three months, I wrote all the content for Draft.dev myself. Because we work exclusively with developer tools companies, finding qualified writers was a unique challenge. I knew I’d have to start bringing in other writers, but I had no idea where to find them.
So, I started by reaching out to people I had worked with in the past. This got us a couple of technical writers, but I quickly realized that I didn’t know that many software engineers who also wanted to write blog posts, technical documentation, and social collateral.
The next avenue I tried was Upwork. I’ve had fairly good results hiring other types of freelancers on Upwork, but in this case, I couldn’t find writers who were actually technical enough on the platform. Our clients run into the same problem with various other gig economy-style services. While they might work great for some roles, the best technical bloggers and writers just aren’t hanging out on Upwork to find work.
Another option that many of our clients have tried is asking their in-house engineers to write. While this can work, it’s really hard to get engineering time reserved for writing blog posts. You’re not likely to get consistent output unless you make technical writing a core part of someone’s job, but that’s usually quite a bit more expensive than hiring freelancers.
How We Find Technical Writers for Hire
Because we’ve been building a writer pool for over five years, we get hundreds of new applications organically every month. That said, in the early days, we did much more targeted outreach, so we were able to establish a repeatable process for bringing on new technical writers for hire.
Here’s how our process works, so you can adapt it to find your own freelance technical writing team:
1. Know What You Are Looking For
Many content managers lean too heavily on writers to pitch them topics for blog posts. This might work for huge companies with the domain authority to rank for nearly everything, but it’s not very strategic.
Instead, talk to customers, do keyword research, and create detailed briefs and outlines for each article before you start looking for a writer. This ensures that you can give your technical writer clear expectations from the moment they start working with you. Once they’ve proven themselves and understand more about your company, let them pitch ideas as well.
Next, use a hiring rubric for your technical writers. This sets clear standards and helps you objectively compare writers, rather than simply relying on gut feelings.
Some writers are good at tutorials, others at high-level guides; some technical writers can create sample applications, others cannot. By setting clear expectations up front, you can avoid reaching out to writers who don’t have the skills or experience you need.
2. Search Dev.to, Medium, and GitHub
Once you know what you’re looking for, use Medium, Dev.to, and Google to look for technical bloggers who are already writing about similar topics. Ideally, you’ll find a few who are strong writers, interested in the topics you need to cover, and have written about them in the past year.
If your product is open source, you can also look through your GitHub stargazers, watchers, or contributors. There’s a chance that a few have blogs linked from their GitHub profiles, so you can see what their writing is like before you reach out.
Add each writer who might be a good fit to your list and look for their contact information. I prefer to reach out only to writers who list an email address publicly, but tools like Clearbit, Hunter, and People Data Labs can all help you find contact information for just about anyone on the basis of very limited information.
3. Reach Out to Each Technical Writer
Armed with a list of potential writers and their contact information, you’re ready to start reaching out. Individualize each email, showing them that you read their work. Be genuine but complimentary.
Finally, be straightforward with your offer. Developers aren’t necessarily jazzed about cold email outreach, but we get a pretty good response rate by not being pushy. We also get straight to the point and respond quickly if they reply.
Here’s an email that got a reply recently:
Hey [NAME],
I ran across your piece on [TOPIC] and had to reach out. You’re a really solid writer, so I just wanted to see if you’d be interested in writing technical blog posts for pay?
I’m a former CTO now running a technical writing company called Draft.dev. We send out a list of writing opportunities to developers on our list each week so I wanted to see if this might be something you’d want to try.
Let me know what you think and keep up the good work!
I typically see a 5-20% response rate depending on how focused my outreach is and the topics we’re looking to find writers for.
4. Understand What Motivates Technical Writers
If you’re hoping to recruit experienced software engineers like we are, it’s really important to understand what motivates them.
For many—especially those with full-time jobs—money is not the biggest motivator. Sure, we pay our writers well, but most of them make more per hour at their day job.
What we can offer is a byline, editorial feedback, and wider distribution than most will get on their personal blog. Plus, the commitment is very casual—many of our writers just write once per month—which can be nice for generating some side income. All these things make writing for Draft.dev a rewarding experience for the right people.
PS: If you’re interested in becoming one of Draft.dev’s technical writers, apply here.
5. Build Inbound Interest
Finally, if you want to increase the amount of technical content you produce, you’ll eventually need to build inbound interest from writers. Here are a few ways to build awareness of your technical writing program and find more writers for hire:
You can set up a writer referral program to incentivize writers to recruit their friends
Add a call-to-action on each of your blog posts under the writer’s byline
Attend meetups for developers and mention that you hire technical writers
Create technical writer-focused content on your engineering blog
Place ads in newsletters aimed at software developers
All these channels work, but depending on the volume of content you need, they may not be necessary. Many new technical content programs just need one or two freelance writers to get things started.
Paying Freelance Technical Writers
When I first started paying technical writers, I had no idea how tricky it could be. I assumed Paypal would be fine, but quickly realized that they don’t service many countries and that they impose large fees on writers.
So, before you start hiring freelance technical writers, consider the following challenges:
Currency exchanges for international writers
Compliance steps for freelance status based on location (think of California and their AB5 bill)
International taxes or laws preventing certain payment methods
Identity theft or fraud (especially if sending physical checks)
It’s also important to do some research to ensure you’re aware of legal requirements inside and outside of the United States. Let’s take a closer look at how you can start paying your writers and some of the tradeoffs to each method.
ACH
Short for “automated clearing house,” ACH is a digital network for low-value direct payment processing. This program uses qualified banks and accounts to support both credit transfers and direct debits, making it easy to deposit money for your freelancer’s completed work.
ACH is a fully automatic payment system, meaning that it completely removes the need to manually handle deposits for individual invoices. This makes it an amazing option for businesses that plan on hiring multiple freelance writers. What’s more, it’s a much safer and more streamlined process than wire transfers, keeping better records of your money over time.
Advantages
Low cost: Unlike Upwork, ACH transfers are extremely cost-effective. The vast majority of ACH transactions do not have processing fees or large costs associated with labor.
Speedy deposits: Some payment systems take several weeks to successfully transfer funds from one account to the next. ACH deposits take roughly one or two days to process, and are sometimes even accessible on the same day.
Disadvantages
Location locked: ACH only works for US-based freelancers. If you are looking to hire a freelance technical writer living outside of the US, this system is simply not going to work for you.
Overdrafting: Because ACH transfers are completely hands-free, they can sometimes lead to overdrafts of accounts, miscommunication, and general concerns about billing. Other billing errors could force you to accumulate fees, or accidentally keep paying for services you are no longer receiving.
Wire Transfer
Wire transfers continue to be one of the most used payment systems for international billing. There are many reasons why they remain popular for technical writers, including ease of access and flat-out convenience. Unfortunately, wire transfers are also used in more nefarious transactions, including scams (remember the Nigerian Prince?). It’s best to know exactly where your money is going while using a wire transfer — or have a lot of good faith in the recipient.
Advantages
Works internationally: Wire transfers allow you to send funds to anyone in any location. If you are planning on hiring a freelance technical writer anywhere outside of the US, you can easily bypass ACH limitations with a simple wire transfer.
Online convenience: Funds can be wired from your bank, grocery store, or even your home office. Chances are you won’t take more than a few minutes to get the job done.
Disadvantages
Costs: Wire funds can quickly rack up additional costs, including transfers, international outbound, and domestic fees. These costs grow heftier the further away you plan to transfer money.
Legal issues: Unlike other types of freelancer payments, wire transfers won’t handle any legal or withholding concerns for you. This is up to your team to handle separately. What’s more, wire transfers are nonreversible. If something goes wrong, you’re on your own.
PayPal
Lots of freelance technical writers prefer getting their payments via PayPal thanks to an easy interface and rapid transfers. While the convenience is tempting, it might not be the best option for your team or current freelancer relationship.
Advantages
Easy to use: It doesn’t take a rocket scientist to figure out how PayPal works. Even if you do get a little tripped up, the company offers plenty of helpful content on how to send and receive funds.
Fast setup: Invoicing and payment plans are free to set up using an email and phone number, resulting in almost no paperwork or red tape.
Disadvantages
Business account fees: PayPal isn’t completely free, though. Business accounts are charged a whopping 2.9% to receive money and transfers, as well as business invoices.
Account suspension: PayPal has full authority to suspend your account for any reason at any time. All funds in your account may be frozen for an undetermined number of days, and it can be frustrating trying to contact support.
Finally, we use Plane at Draft.dev. Not only does it make paying freelancers around the world (we pay writers in 56 countries now) easy for employers, they don’t charge freelancers and make currency conversion seemless. Plane also handles compliance and legal concerns by giving you country-specific contracts and collecting W8/W9s from your freelancers.
Advantages
Works in any country: We’ve paid writers all over the world, so as long as it’s legal to pay people in that country, Plane should support it.
Compliance and legal documents: In addition to letting you run payroll, Plane collects legal documents like contracts and tax forms.
Customer support: If anything goes wrong or a payment ever goes missing, Plane’s support is quick to respond and help out. This saves a ton of time when you’re paying lots of people every month.
Disadvantages
Employer fees: While freelancers don’t pay to use Plane, the employer does pay a monthly fee per contractor or employee. For international contractors, this is currently $39 per month.
Drawbacks to Hiring Your Own Technical Writers
Now, even if you find a few great technical writers for hire, you still have a lot of work to do. You have to plan your topics, create due dates, and track each article as it’s assigned. You will also need to hire or work with an editor and technical reviewer.
While writing samples will help you avoid really bad technical writers, every article will need at least a light round of editing. You also have to watch out for plagiarism, AI-generated content, and the misuse of copyrighted images, as well as assess the technical quality of their work.
If you’re trying to find a technical writer for hire but you’re feeling stuck, reach out to us. At Draft.dev, we build content-powered growth engines for that compound and resonate with developers, search engines and LLMs. Proven AI workflows and 300+ subject matter experts ensure fast turnaround times (within weeks) and high quality.
With hundreds of active writers at Draft.dev, we’re able to cover a wide range of technical topics for tutorials, blog posts, ebooks, and more. We can provide consistently high-quality content that is professionally edited and technically sound without the management overhead required to assemble your own team of freelancers.
When Karl Hughes founded Draft.dev in 2020, he identified a universal challenge in the tech industry: companies with innovative products consistently struggled to create technical content that genuinely resonated with developers. Marketing teams lacked the technical expertise to write convincingly for this audience, while engineering teams focused on building products, not content.
Draft.dev’s solution? Build a specialized agency bridging this gap with a network of practicing technical professionals who could create authentic, valuable content specifically for developer audiences.
Expanded our network from a handful of writers to more than 300+ technical subject matter experts
Worked with more than 150+ technical companies, ranging from early-stage startups to enterprise companies
Delivered more than 4000+ pieces of technical content to clients
Maintained a consistent focus on serving technical audiences
Why Technical Content Drives Business Growth
Our inclusion to the Inc. Regionals list validates what we’ve believed from day one: high-quality technical content is a critical business driver for technology companies. Through our work with clients ranging from startups to enterprises, we’ve proven that technical content can:
Drive awareness by creating a consistent cadence of valuable information that attracts the right audience
Capture leads through strategic content that converts passive readers into engaged prospects
Build trust by demonstrating deep subject matter expertise that technical decision-makers respect
The Draft.dev Difference: What Sets Us Apart
What has fueled our growth—and earned us a spot on the Inc. Regionals list—is our unique approach to technical content creation:
Subject Matter Experts Writing for Their Peers
We don’t believe in generic content. Our network consists exclusively of practicing technical professionals with hands-on experience in the technologies they write about.
Consistent Quality Through Professional Editing
If you’ve worked with freelancers before, you know quality and reliability can vary. Our team of editors and technical specialists ensures that every piece is technically accurate and meets our rigorous quality standards.
Content You Can Count On
Our structured process ensures predictable, high-quality delivery you can build your marketing strategy around.
Focus on Measurable Results
We partner with clients to establish clear metrics for content performance and optimize based on data. Our Lead Generation Package provides comprehensive campaign strategies with analytics reviews to track content effectiveness.
Thank You to Our Community
This recognition wouldn’t be possible without our dedicated team of writers, editors, technical specialists, content strategists and the visionary clients who trust us with their technical stories. We’re grateful for the opportunity to continue creating the highest quality content for technical audiences.
As we celebrate this exciting milestone, we remain committed to our mission: helping tech companies create successful content programs that drive awareness, capture leads, and build trust with technical audiences.
TL;DR: Comprehensive collection of technical writing resources covering:
Style and editing – Style guides, editing techniques, and B2B writing strategies
Documentation – Best practices and real-world examples from top developer tools
Career development – Resume tips, cover letter examples, and entry-level opportunities
Content formats – Tutorials, comparisons, roundups, and persuasive technical content
Written by practicing technical writers and editors with real-world experience.
What Are the Best Technical Writing Resources?
Technical blogging is our specialty at Draft.dev, so we invited our best authors to compile their tips for technical writing here. Whether you’re writing for your personal blog or your company’s engineering blog, these resources can help you hone your skills as a writer.
TL;DR: The best technical writing style guides for documentation teams in 2026 are:
Google Developer Documentation Style Guide (5.0/5.0) – Most comprehensive with enhanced AI translation support and updated accessibility standards
Microsoft Writing Style Guide (4.9/5.0) – Industry standard with continuous web updates and defined voice attributes
GitLab Documentation Style Guide (4.8/5.0) – Living document approach optimized for AI tools like GitLab Duo
Apple Style Guide (4.7/5.0) – Comprehensive product-specific guidance updated June 2025
DigitalOcean Guidelines (4.6/5.0) – Best tutorial framework with ready-to-use templates
These guides share three universal principles: know your audience, establish a distinctive voice, and prioritize clarity. Each provides unique frameworks for creating consistent, professional technical documentation in an AI-assisted writing era.
In technical writing, consistency builds confidence and creates opportunities to develop communities around documentation. As AI tools become integral to documentation workflows in 2026, following established style guides has become even more critical for maintaining quality and human expertise.
How do you make your technical documentation more consistent? Adhering to a technical writing style guide is essential. A style guide defines communication standards for all technical documents your business produces, covering voice, structure, and technical conventions for text, audio, and images.
Since style guides are comprehensive, they can be challenging to create from scratch. Fortunately, many companies have made their technical writing style guides publicly available and continuously update them for modern documentation needs, including AI integration and translation optimization.
Draft.dev Style Guide
The Draft.dev Technical Blogging Style Guide is a good place to start. It’s used by several technical writers who cover a variety of topics, mainly because it sets down the basics of style decoupled from any context that’s too specific. This guide breaks style into the following four sections:
Voice: It recommends using the second person (you, yours) to engage the reader and establish a clear point of view.
Content: The guide recommends a certain structure for blog posts and demonstrates how to support claims with evidence while avoiding plagiarism.
Conventions: This section sets standards for formatting, such as using Markdown and how to add images to a post.
Communication: This section emphasizes the importance of keeping in communication with the editor or publisher you’re working with and letting them know of any roadblocks as you write.
As you can see, it’s a technical blog post about how to write a technical blog post—a nice meta style guide.
A List Apart
The style guide from A List Apart is an example of a valuable, reader-centric, but more informal style guide. It offers advice about text formatting, assets like images and author bios, and some notes about how to refine the content itself.
One of the more unique features of this style guide is its discussion of the use of metaphors. A List Apart advocates clarity first. It also suggests following The Chicago Manual of Style and Fowler’s Dictionary of Modern English Usage as principal references for proper language usage.
As of 2026, DigitalOcean’s Write for DOnations program is reviewing its backlog and was paused for new topic submissions until 2025. The core technical writing guidelines remain available and continue to be referenced, though the community tutorial submission process has been restructured. The guidelines last received major updates in 2022 and remain relevant for tutorial-style technical documentation.
The four sections of the guide are:
Style: This is further split into four sections that cover clarity, level of detail, completeness, and tone. It encourages you to write for all technical levels by avoiding assumptions of previous knowledge, giving context for code, and writing “friendly but formal” pieces that show respect for cultural differences.
Structure: DigitalOcean’s guide is very specific about the desired structure for its articles. This section includes examples for various article types and includes some ready-to-use templates.
Formatting: This section outlines how writers are expected to format their work using an extended version of Markdown. It provides examples of supported extensions.
Terminology: DigitalOcean has established some conventions for writing examples, such as a standard default username, default hostnames and domains, and how exactly to indicate to readers where they should alter text with their own input.
DigitalOcean’s technical writing style guide is easy to read and very focused on system administrators and software engineers. The terminology section and linked guides for best practices and code of conduct go a long way toward guaranteeing a high level of quality in the writing.
SUSE Documentation Style Guide
SUSE Documentation Style Guide is a comprehensive and detailed guide to updating documentation for well-established software products like SUSE’s. It starts with simple but powerful advice: define your audience. This sets the level of expertise assumed for the reader and the context in which the documentation will make the most sense.
The guide provides the three following key points about the content itself:
Avoid promising future features, which are not relevant to the current stable product
Include warnings on features scheduled for deprecation
Clarify the status of unsupported features before documenting them
The guide includes more useful details, such as conventions for terminology used in examples (similar to DigitalOcean’s Terminology section) and how to format various content types, like manuals, books, and articles. The defined format is GeekoDoc/DocBook markup language, and the guide includes an extended description of its tags.
The IET Guide to Technical Report Writing
The Institution of Engineering and Technology (IET), an organization with roots dating back to 1871, provides a concise guide covering many important aspects of technical writing. Its first section provides ten laws of good report writing, which you should definitely keep close when you write. Spoiler alert: the first and last laws are the same—write for your readers.
The guide’s next sections complement those ten rules, with discussions about:
Objectives: Determining why you are writing and who you are writing for
Format: How to structure your writing and reference citations
Writing: The nitty-gritty of writing, including sentence structure, what a paragraph does, and striking the proper tone
Diagrams: Determining proper placement and facilitating ease of understanding
Finishing the report: Polishing the piece with summaries, tables of content, and proofreading
In the Writing section, the example about the use of commas is worth noticing for how precise the guide can get:
The engines, which were in perfect running order, had been tested previously. (all engines were in perfect running order and had been tested) The engines which were in perfect running order had been tested previously. (only the engines in perfect running order had been tested)
The Apple Style Guide was most recently updated in June 2025 and remains available as both a web interface and downloadable PDF (243 pages). It provides comprehensive guidelines for maintaining consistent voice across Apple materials, including documentation, reference materials, training, and user interfaces.
Highlights:
Extensive glossary covering proper usage of Apple product names and features.
Tips for writing for international audiences with limited English proficiency.
Focus on helping human and machine translators localize content effectively.
Product-specific guidance for referring to Apple ecosystem elements.
Drop-down navigation for streamlined information access.
The Apple Style Guide references Merriam-Webster’s Collegiate Dictionary and The Chicago Manual of Style as foundational resources. It encourages technical writers to minimize cultural and language barriers by following international style conventions.
Note: Some Apple departments maintain supplemental guides for specific use cases. The guide is English-only with no Japanese or other language versions currently available.
GitLab references both Google and Microsoft style guides as supplementary resources while maintaining its documentation-first methodology, making technical documentation the single source of truth for product implementation, usage, and troubleshooting.
Best For: Teams seeking an evolving, community-driven approach with built-in automated quality checks and AI translation optimization.
Google Developer Documentation Style Guide
The Google developer documentation style guide continues to be actively maintained, with the last update in December 2025. The guide has evolved significantly to address AI-powered translation and machine learning systems.
The guide is very dense and has several sections, so here are a few highlights:
Accessibility: Voice, tone, keyboard navigation, screen reader support, inclusive language, and HTML formatting.
Language and grammar: Guidance on avoiding anthropomorphizing software products and proper verb forms in API documentation.
Linking: Standards for creating readable, accessible links.
Computer interfaces: This section pays special attention to documentation guides for application programming interfaces (APIs).
Markdown versus HTML: Clarifies that HTML offers more expressiveness despite Markdown’s readability advantages.
Expanded Definitions: New standards for binary/decimal units, image referencing, and placeholder styling.
Updated Word List: Continuously refreshed terminology reflecting current technology trends.
Microsoft Writing Style Guide
Many other sources reference the Microsoft Writing Style Guide as a source of answers for technical writing. Some reasons for this include its wide scope (which covers writing content for chatbots and virtual agents) and its sections on content and design planning, scannable content, and selecting words to improve readability and comprehension, among other useful information.
But the heart of the guide is in its definition of voice:
The Microsoft voice is how we talk to people. It’s the interplay of personality, substance, tone, and style.
The Microsoft brand voice has three clearly defined attributes:
Warm and relaxed
Crisp and clear
Ready to lend a hand
You should explore the entire guide to check how these attributes are expressed consistently in each section. It covers scenarios that range from creating a scripted chatbot to writing responsive content for the web. Take note of how the tone can vary depending on the context of the documentation. Your own brand voice should be distinctive and tell your readers what to expect of your company.
Red Hat Technical Writing Style Guide
The Red Hat Technical Writing Style Guide is a comprehensive open-source resource designed for technical writers working on enterprise software documentation. Updated regularly through its GitHub repository, it provides practical guidance for documentation teams.
Key Features:
Open Source Approach: Available on GitHub with community contributions
Modular Writing: Guidelines for breaking complex topics into digestible sections
Inclusive Language: Strong focus on avoiding biased or exclusionary terms
Screenshot and UI Standards: Detailed guidance for visual elements in documentation
Command Line Conventions: Specific standards for documenting CLI tools
Best For: Teams documenting open-source projects, enterprise Linux systems, or cloud-native technologies.
Conclusion
After reviewing all the referenced style guides, the common elements remain consistent for 2026:
Know your audience and write for them
Set your own voice
Keep content simple, short, and clear
New: Optimize for AI translation and machine comprehension
While these principles provide a foundation, detailed formatting guidelines, glossaries, and standard structures continue to evolve. The most successful documentation teams in 2026 combine established style guide principles with AI-assisted workflows while maintaining human expertise and editorial oversight.
A good starting point is to take the best parts of available resources and build your own custom style guide. As AI tools become more integrated in documentation workflows, maintaining clear human-authored guidelines becomes even more critical for quality control. For more tips on technical content strategy, visit the Draft.dev blog.
You’ve been tasked with some highly specialized material to edit. You’re a pro at writing, but this topic is outside your area of expertise. Now what?
Don’t panic. I’ve got years of experience and a bunch of editing tricks to pass along.
Understand Who Your Writer Is
First, it’s important to understand who the writer is on a professional level. In most cases, the writer of the piece you are editing is a subject matter expert first and a writer second. You can probably trust that the content is correct, or at least that a technical reviewer has given it a stamp of approval. That means you can focus on the quality of your writing.
How much writing experience this expert has can vary greatly. You may be working with a seasoned voice of authority who’s written their own blog for years, or you may be working with a junior developer writing their first tutorial. Knowing this will inform the depth of the edit you should be prepared for. Obviously, a more experienced writer will need a lighter edit than someone who’s just starting to write professionally.
Either way, strive to treat the author with the same respect no matter their writing experience. But we’ll talk more about communicating with writers later.
Do Some Content Research
If you’re going to be working with complex technical content, you’ll have to do some research. Being able to write on the topic yourself isn’t a requirement, of course, but if you’re out of your depth, reading at least the intro paragraph on Wikipedia can get you familiar with a few keywords.
Handling Unfamiliar Jargon
Familiarizing yourself with keywords around the topic is important because, no surprise, technical docs are full of jargon. Jargon can often come across as poor spelling or grammar if you don’t recognize it.
Fortunately, you can usually satisfy the question, Is this a Tech Thing or is this just awkward writing before introducing errors with a well-intentioned but uninformed edit:
Search online for the phrase as the author has written it. If it’s commonly used in the industry, you’ll see it pop up regularly in similar content.
Double-check the intended audience. Hopefully, this is information you received when taking on the project. If not, this is a perfectly reasonable question to ask.
If the audience is, for example, junior developers or nontechnical executives, you may decide to go ahead and ask the author to reword for broader accessibility.
If on the other hand the audience is, say, senior developers, leave the jargon in the article as is.
If you can’t find the jargon with an online search, query your contact (presumably either the writer or whoever assigned you the project) and ask for clarity.
Handling Unfamiliar Concepts
A talented writer will craft sentences you can easily follow, even if you don’t understand the technicality of the content. As an experienced editor, you’ll be able to see points tie into each other and recognize smooth transitions into new sections of information. You know what a good sentence looks like; you don’t necessarily have to understand what every word in the sentence means.
However, you may run across a few paragraphs that impede this smoothness. The concept just isn’t falling into place, or the shape of the writer’s point is still too vague. Has the writer just made some assumptions about their readers’ knowledge and they’ve elected to simply skip over a few details? Is there really material missing that readers need to be able to follow an idea successfully? Or is your writer out of their own depth and the writing is actually weak or inaccurate?
First, try a short online search before querying your author. Remember, you’re working with very technical content written by and for people with a specific knowledge set. You can’t afford to ask for explanations on everything you as the editor are personally unfamiliar with. Not only would that lower your writer’s confidence in your edit, it would also waste time, and you probably have a deadline.
As a general rule, don’t ask questions you can answer for yourself with a quick search. If you’re still unsure, try to ask the project manager (eg, your supervisor or your assigning client) or leave a comment for the writer in the document.
Understand the Type of Edit You’ve Been Asked For
If you’ve been editing for any length of time, you probably appreciate that there are different types of edits. What have you been asked for? A developmental edit? A line edit? A copy edit?
Take care to adhere to the type of edit you’ve been asked for as much as possible. If you’ve been asked for a copy edit, for example, the amount of research you’ll have to do will be considerably less than the other two.
If you do run across something that’s outside the bounds of the edit you’ve been asked for, but you still feel strongly that something needs to be adjusted, leave a comment with a suggested edit. If the entire document needs a heavier edit than what you’ve been asked for, it’s time to get in touch with your manager and let them know you need to make heavier edits.
Avoid Rewriting…Until You Can’t
The line between editing and rewriting can get blurry, but here’s my quick and dirty differentiation:
Editing: Word-by-word adjustments, retaining the author’s voice while clarifying their meaning.
Rewriting: Scrapping what the author wrote entirely and creating something new from scratch. Sometimes this means half a sentence, sometimes this means an entire section.
When it comes to complex, technical material, avoid rewriting. The possibility of introducing errors is high. If something is simply not clear, query the writer.
If you feel a rewrite is unavoidable, and you’re itching to make your own words appear on the page, make sure these boxes are checked first:
You’ve been asked for a heavier edit.
You have appropriate knowledge of the subject matter.
The writing skill has been consistently rough.
An inexperienced writer may appreciate that they don’t have to redo a lot of work (that they may not have time for—your technical experts will most likely not be writing as their day job). An experienced writer will not thank you for rewriting their material when a simple query would let them know they need to rework something. Before you rewrite, make sure you’re assessing the situation correctly.
A Word About ESL Edits
When it comes to complex, technical material, it’s not uncommon for authors to be writing in a non-native language. For English-as-a-second-language (ESL) writing, keep the following tips in mind as you edit:
Be mindful of their voice in English. Would they probably not use a baseball idiom? Do they avoid compound sentences? Don’t introduce them with your edits.
Punctuation and capitalization have different rules in different languages. English punctuation alone varies between countries (US vs. UK) and style guides (CMS vs. AP). Quietly tidy up copy edits according to the style guide your publication is working with.
Be respectful and don’t condescend. You are an expert in writing and editing. They are an expert in their subject matter. Recognize that you are helping each other bring a finished product into being, and keep your queries to the writer professional and respectful.
Raise the Alarm for Big Problems
Occasionally, you’ll run into problems an edit just can’t handle. You may suspect that your writer has oversold their own knowledge of the subject matter, or perhaps your research uncovered the fact that your writer has plagiarized.
These problems don’t go away, and if they make it to publication, they can explode in a bad way. Reputations can get called into question, business can be lost, posts can be deleted, and apologies can be necessary.
Inaccurate or Superficial Writing
If you suspect that a writer is simply not capable of writing the material accurately or at sufficient depth, it’s time to call in another expert. If you already have access to a technical reviewer, fantastic—have them look over the piece, highlighting your areas of concern. Otherwise, let the manager know there’s an issue and ask them to suggest a suitable expert, perhaps another developer they trust, for example.
Hopefully the second expert can suggest more specific ways to request that the writer add new information or correct what’s in error. However, be open to the idea that the piece simply may need to be rewritten by someone else, understanding that it will most likely mean a new expense.
AI Use
If you’re an experienced editor, it’s pretty easy to spot AI-generated content. Typically, you’ll see:
Sentences that say the same thing.
A paragraph or sentence that doesn’t say anything new.
Points mirroring the outline without adding any depth.
Unnecessarily flowery and wordy phrasing.
After cutting any repetition or wordy content, make sure the content you’re editing still has substance. If it doesn’t, you’ll need to ask your writer to expand (in their own words). If the writer can’t expand, they’re likely in over their head and it’s time to bring in the experts.
At Draft.dev, we’re not totally against AI, but there’s definitely a time and place for it. AI struggles with going deep into complex topics. If you’re editing for a highly technical audience, it’s best to probe your author to go deeper and add personal experience, something an AI tool can’t offer.
Plagiarism
If your writer is inexperienced, they may not understand how a quoted citation makes verbatim use of research okay, but it’s plagiarism otherwise. The constant cross-sharing of internet content only blurs the line further.
Plagiarism checkers are a thing, but you can also develop an eye for the red flags yourself:
A well-written sentence in the midst of an otherwise poorly written article.
A paragraph with a suddenly different tone/voice.
Points or sentences that seem to contradict each other (this can also be a sign that an author may not quite have the knowledge base they need or didn’t do careful enough research).
Googling the sentence in question can turn up the original article it was pulled from (Wikipedia articles and other authoritative blog posts are the usual suspects). For a first offense, leave a nonaccusatory, professional query requesting a rewrite in the author’s own words, or a proper quote and citation if a rewrite doesn’t make sense. Obviously, an article that is entirely quoted paragraphs is not acceptable either.
If plagiarism is a pattern with a writer, it’s time to let them go. Their material will be time-consuming to edit, the author’s rewrites will be poorly done, or worst case, you may have to bring in another writer entirely. That’s time and money no one wants to spend. Again, politely and professionally bring this to the manager’s attention.
Conclusion
Highly technical content isn’t the easiest material in the world to edit, but with care and attention, it can be done well. Know your writer, know your audience, know when to ask questions, and be prepared to put in some research, and you’re well on your way to crafting publishable work that’s helpful to its audience.
It does take time to become a skilled editor, of course, and it’s not feasible for every business to employ their own editorial team for their technical publication. If you’d like to publish polished, informative technical writing without taxing your own staff, contact us at Draft.dev to see if we can help.
TL;DR: B2B writing communicates business value through clear, professional content tailored to specialized audiences. Essential types and tips:
Six Core Types: Blog posts (500-2,000 words), email marketing (under 200 words), ebooks/whitepapers (500-2,500 words), product descriptions, ghostwriting, and press releases
Key Principles: Start with clear goals, build outlines, write conversationally, use industry jargon strategically, develop consistent brand voice
Success Strategies: Balance SEO with human readability, always proofread with human editors, focus on audience pain points, maintain professional tone without unnecessary complexity
Consider freelance B2B writers, marketing consultancies, or specialized content agencies for professional support.
You’d never accuse business-to-business (B2B) writing of being effortless or easy to do. And in a world now flush with more than 4.27 billion pages of digital writing, there’s the added complication of cutting through the clutter.
You walk a fine line with B2B writing — it must be clear, concise, and yet friendly and easy to read. Imbuing your pieces with a human touch can also help readers engage with your brand.
Sound impossible? Not quite. And contrary to popular belief, it’s a skill that can be learned.
If you’re willing to practice and try new things, you too can discover how to do B2B writing right.
B2B writing is exactly what it says on the tin. It’s written communication from one business to another, often illustrating how your business can help the other.
Have a tool or service or product that you’ve built to make another company’s workflow easier, say a hosting platform or a CI/CD SaaS? You need to communicate the benefits of it with B2B writing.
Writing for B2B markets is noticeably different from business-to-consumer (B2C) writing in a handful of subtle but important ways:
You’re writing to a much more narrow demographic with more specialized knowledge
Your audience expects a certain level of knowledge from you
You can use more industry-specific jargon
Explanations of well-understood industry concepts can be skipped or kept brief
To illustrate this, here’s an example of B2B writing:
Now here’s an example of B2C writing:
Notice the tone shift. See how the audience has changed? You’re no longer speaking to business owners and decision makers. Instead, you’re chatting directly with consumers.
6 Types of B2B Writing
B2B writing is a rather broad term, but within that are several different types of writing. Each of these have a unique purpose and require different structures, approaches, and tones.
Let’s start with the most common type of business writing:
1. Blog Posts
A B2B blog post usually takes the form of an informational essay of between 500 to 2,000 words. You may want to post these on your own company’s website, or write guest posts about your services and products for informational sites (think online magazines or other companies’ blogs).
Depending on your brand voice and the voice of the website, you can perhaps indulge in a more informal tone. They must still bring some value to the table, though — 35% of blog readers skim content, so you must prove at the beginning why they should keep reading.
Most of you are probably familiar with what a B2C blog post looks like. When they’re well done, they can be witty and entertaining. Unfortunately, we’ve all seen the infamous cooking blog posts that ramble for hundreds of words before getting to the point the reader is there for: the recipe.
B2B blog posts especially need to get to the point. You’re writing 1,000+ words for a reason. What is it?
Whether it’s a tutorial or discussing company philosophy, keep your theme at the forefront of the piece. Never let your readers wonder why they’re reading your blog post.
2. Email Marketing and Newsletters
Effective email is short and sweet. B2B marketing emails in particular must have a tightly defined point, clearly expressing what you’d like the recipient to do after they read your message.
Should they use a coupon code? Sign up for a webinar? Join a beta? You should get this message across in 200 words or less.
Depending on the email and your brand voice, you can probably afford a witticism or two. But when in doubt, keep it straightforward.
Readers will be skimming your email, so help them out with clear language and easy-to-understand formatting. By all means, use a visual, a photo, or graphic if it will help convey your CTA faster.
Newsletters can afford to be a bit lengthier and less tight than an email, especially if you’re an established voice of authority. But when in doubt, just address the why and how. Remember: you want your audience to want to listen to you.
3. Ebooks and Whitepapers
Whitepapers and ebooks explain the technical aspects of how your product or service would fit into a business structure. The length of either can be a bit ambiguous, but it honestly depends on what you want them to do.
Do you have 40,000 words of opinion on open source as a philosophy? By all means, get your ebook nicely formatted with some good graphics.
But a more likely scenario is that you want a handful of whitepapers for your sales team or prospective client to read.
First, anticipate the questions of your target demographic and answer their concerns clearly and professionally. This could cover a couple of pages (500 words) or range up to ten (around 2,500 words).
You next need to consider whether your topic should be broken down into a series of whitepapers or an ebook.
For whitepapers especially, due to their technicality, the tone is professional and polished. Ebooks definitely have a more informal tone, but they’re likely still more formal than your typical brand voice.
4. Product Descriptions
One of the biggest gaps I notice on tech company sites is a clear product description. You know what your product does, but does your target demographic? How quickly can they figure out what you do?
Aside from your infographics, or your brand colors, or your landing page, make sure you have a short paragraph that reads:
“Amazing Product is a noun that verbs this pain point by specific description of integration with client workflow.”
That’s all a product description needs to be.
But I know this can be tricky, especially for startups.
You can start by asking yourself some questions:
What is your product? Don’t just describe it as a solution and call it quits.
What pain point does it address? And for whom?
How does it address the pain point? Is there specific lingo you should use?
And while we’re on the subject of lingo — don’t get too carried away with semantics and abbreviations. Asking readers to wade through buzzwords is also asking for a high bounce rate.
Stick to your brand voice as you write your product descriptions, and try to be clear and transparent too.
5. Ghostwriting and Speeches
If you’re the primary writer for your company, chances are you’ll be asked to put someone else’s meaning into words. Your CTO may be the voice of authority on a topic, but they may not have the time or skill to get it down on paper.
Ghostwriting is a bit different from the other types of B2B writing we’ve covered so far. While the basic principles still apply — be straightforward, be clear, keep your point at the forefront of the piece — you also have to remember you’re taking on the voice of a particular person.
If your CTO is pretty down to earth, don’t inject five-dollar words into a speech they’re going to deliver (or a blog post that will have their picture next to it). It’ll ring false, which can make the piece all but worthless.
As the name suggests, a press release is meant to release news to a press. You’ve raised a round of funding, you’re getting ready to release a new version, you’re discontinuing a legacy service — and you’d like to inform the industry.
There are guides galore on how to write a press release, and even more tools to help you distribute them. I won’t belabor the specs myself, but I will emphasize that structure matters here — possibly more than any other piece of B2B writing I’ve touched on.
So please glance over a few tutorials, find the commonalities, and stick to them religiously.
The press release is an efficient formula for delivering information to people who will transfer it to another format, usually a news article or industry blog. These people are looking for specific info to craft their own writing, and the press release is designed to help them find it easily. Mess with the formatting too much, and your press release is going in the trash.
Tips for B2B Writing
As you’ve read so far, there are a lot of different structures that B2B writing can take. But no matter whether you’re writing a blog post, a whitepaper, or a webinar script, there are a handful of best practices to keep in mind.
Start with Your Goal
What do you want your audience to come away with? What do you want them to know by the end of your piece? Distill that into a single sentence and make sure that idea informs the rest of your writing. Write it down if you like, then keep it physically close while you craft the rest.
In his B2B copywriting guide, Sean Begg Flint advises starting with your audience’s main pain points. When you keep their challenges front and center, your writing becomes immediately relevant and actionable.
Build an Outline
You probably don’t have to do this for an email or product description, but for long-form pieces, an outline is a huge time saver.
Consider how each step will get you closer to your goal, then build logical steps to make the piece a reality.
The brevity of an outline forces you to stay on point (or at least makes it easier to see when you’re wandering or when a point doesn’t fit easily with its neighbors). When you’re stuck in your draft, you can revisit your outline to see where you’re supposed to go next.
To be honest, writing an outline is my least favorite part of writing. But avoiding multiple revisions makes them worth it, hands down.
Remember how I said not to use five-dollar words for ghostwriting? The same applies to non-ghostwriting. If you try to write with vocabulary you don’t normally use in speech, you’re going to confuse your audience and push them to a more clearly-written piece (possibly written by a competitor).
Being professional in your tone doesn’t mean introducing unfamiliar styles of speech. Stick to avoiding profanity and questionable humor, and ta-da, you’re probably being very professional, actually.
Use Tools
If you could use some extra confidence in your writing, or you’d like a sort of digital editor to look over your shoulder, it’s never been easier to level up your own work. Tools like Grammarly and the Hemingway Editor can alert you to flowery language, repeated words, lengthy sentences, and incorrect vocabulary. On top of that, using an AI detector can help you verify whether your content reads as human-written or shows patterns of AI generation.
As I mentioned at the beginning of this article, a certain amount of jargon is expected for a B2B audience. But there’s no need to balloon your word count explaining things you expect your clientele to already know.
Don’t miss an opportunity to lead someone deeper into the industry because your writing is unnecessarily opaque. Will it take less than five words to offer a definition for a technical term on first use? Consider including it.
That’s another good rule of thumb, by the way — define a term or acronym once (when you first use it in a piece), then never do it again. Trust me.
Develop a Voice
Humans like to read the words of other humans (we’re a self-absorbed species like that). In writing, voice is the concept of a writer’s style: their tone, their attitude, the vocabulary they use. Are they casual, are they intimate, are they funny, are they educational?
If you’re writing pieces that have your name next to them, consider how you want yourself to be perceived. Don’t feel bad if you can’t get there immediately! Voice is something personal and layered, and it’s constantly evolving, so give yourself time.
If you’re writing marketing material that’s meant to reflect the company and not a person, make sure you discuss what the brand voice is with stakeholders. Take time to get it synced up, too. Your audience can quickly tell if your blog has a different voice than your products page than your whitepapers.
Remember: nobody benefits from a murky brand image.
Have Material Proofread
Perhaps you don’t need a knock-down-drag-out edit, but typos are horrid little things that can hide in plain sight when you’re the one who wrote them. At the very least, get a second pair of eyes — human eyes, not just a digital editor — to glance over any public-facing B2B content. Everyone needs an editor, and the ones who say they don’t are lying.
Consider SEO
Search engine optimization is its own entire thing, so I won’t cover too much ground on it here. Educate yourself on best practices for SEO, but keep in mind you’ll need to strike a happy medium between human readers and robots.
In my humble opinion, leaning toward writing for a human audience rather than a bot can help you avoid SEO faux pas like keyword stuffing.
And please, think critically about the use of AI. Low-effort content won’t do you any favors, especially after Google’s massive spam update.
Learn to Love the Process
Nobody writes anything perfectly the first time theirs fingers hit the keys. Improvement happens with work, so:
Get into the habit of rereading your draft before sending it on down the pike; you’ll be amazed how much you can catch with a simple reread after letting a draft sit for a day.
Revisit your outline and make sure you’ve hit all the points. Then, be sure you’ve hit them as solidly as you wanted to.
If you ask someone to proofread the piece, set your ego aside and carefully consider their feedback. Learn to embrace the learning and use it to fuel your writing in the future.
Where to Get Help with B2B Writing
The writing that surrounds your business is one of the first points of contact your audience will have with you. Polished, professional, and thoughtful B2B writing will go a long way toward a positive first impression.
Are you an authority in the industry? Can your business be trusted? What are your business ethics? How do you want to improve the world?
Those questions are just the tip of the iceberg, whether or not you mean to convey them in your writing.
Clearly, it’s important to make sure the writing attached to your company isn’t an afterthought. So if you’d prefer to offload the writing — I get it, it’s time-intensive and not enjoyable for everyone — you have a couple of options.
Let’s start with the most obvious:
B2B Freelance Writers
There are dozens of world-class freelancers out there who offer B2B content writing. Many of them also have prior experience working in the industries they write in — a major advantage for you and your team.
Freelance writers are also much cheaper than your average marketing agency. Just keep in mind they don’t always provide all the bells and whistles (like social media collateral, for example).
And a word of warning: not all B2B copywriters work at the same level. Some are less familiar with SEO best practices, while others aren’t familiar with your specific industry.
Do your homework before hiring an extension of your team. And if you don’t want to get this hands-on with a writer, you may want to consider a consultancy instead.
Marketing Consultancy
Marketing consultancies do exactly what you think: provide consultation on best B2B writing practices so you can implement them in your business. This is a fantastic choice for the busy marketer looking for support. It’s not as hands-off as working with an agency, and you still have more control than you do with freelancers.
But if you’re looking to delegate your B2B writing work, or if you’re trying to upscale your business writing tasks, consultancies may not offer the automation or instant results you want.
Which leads to a third option:
Marketing Agencies
The marketing agency is a powerhouse of support for the full circle of B2B marketing. Some of them specialize specifically in content writing, while others offer keyword research, topic ideation, and much more.
If you’re looking for marketing strategies like these, check out Draft.dev. We work with B2B writers who are subject matter experts to create blog posts, tutorials, and other content for technical audiences — now with social media collateral and video tutorials!
After days and months of toiling, you finally finish creating your game-changing product that will shake the developer world. You invest a large amount of resources in marketing and find some customers. But surprisingly, instead of seeing your product getting praise from critics all around, you notice that developers are leaving poor reviews and expressing frustrations. They say that your product is “too complicated” and “difficult to understand.”
This is a very common story and is one of the big reasons you should invest in writing good documentation for your product. The documentation is the relationship manager between your product and the developers. Good documentation makes the life of developers easy by explaining the features of your product, whereas bad documentation can frustrate and drive away the developers, even if your product is superb and does a fantastic job! Good documentation also lifts the burden from your support team because if developers can get answers to their questions from the documentation, they won’t need to bother the support team with their issues. Believe me, no developer likes filling out a form and waiting multiple days for an answer from the support team when they can get their answers from the documentation.
The other article explained what makes documentation good. In this article, you’ll see some real-life examples of good documentation. You can take inspiration from these amazing documentation examples and apply the learnings the next time you create documentation.
12 Best Documentation Examples
Before you jump into the list, let’s take a moment to understand the parameters these entries have been judged on:
Depth of documentation: Documentation must be in-depth. This means it must cover all features and all the different ways to use the tool, including installation, setup, configuration, and advanced usage. Bonus points if a quick-start guide is provided that helps developers get started with the product quickly.
Examples: The documentation must have enough examples, and the examples should cover as many use cases as possible. The examples should be complete and understandable to someone who has never used the tool before. Bonus points if the examples are interactive and can be run directly from the docs.
UI/UX: Having detailed documentation is not enough if the UI/UX is bad. The UI should be clean and easy to use. It doesn’t have to be super flashy, but it needs to strike a balance between looks and materials. The UX should also be aimed at making the lives of developers easy. For example, in some documentation, if an API uses an API key and you’re logged in, it automatically populates the API key by taking it from your account.
Search and navigation: It doesn’t matter how detailed the docs are if finding things becomes as hard as finding a needle in a haystack. A search feature is a must in any documentation, and the search experience should be good. Features such as autocomplete, autosuggestion, and fuzzy searching are always appreciated. Navigating the docs is also another closely related issue. Navigating the docs must be easy, with enough internal and external links, and the docs should be structured in a way that makes sense.
Now, without further ado, let’s get to the list.
Note: This is not an exhaustive list by any means. This list is purely opinion-based, and you might find a tool that you feel has better documentation than any tool in this list. Remember that the goal of this article is to inspire you, not to judge tools based on their documentation.
Stripe
Stripe is revered by developers as having one of the best documentation. The documentation home page is designed neatly with tabs at the top that link to the documentation for each product, such as Payments, Developer tools, and No-code. The home page also shows some example snippets that give an idea of some of the important functions of the tool at a glance:
The documentation provides great starting points in the form of quick starts and clonable sample apps. The documentation covers a wide range of ways to use their products, including APIs and SDKs.
The documentation is accompanied by adequate examples. Each example is in-depth and complete. And the best part is that you can choose the language and framework of the examples. You can also mix and match frameworks; for example, Android SDK, Kotlin frontend, and PHP backend. If you’re logged in, the examples will fetch the API keys from your account and populate the appropriate fields in the examples, which makes it easy for you to copy-paste the examples as is:
The examples also have optional sections that provide more ways to customize your experience:
Stripe boasts a superior search functionality that can show results from all over the docs and example code snippets. It also supports fuzzy searching:
Finally, you have the option to contact support or sales from any page:
Overall, Stripe provides remarkable documentation, with its amazing UI/UX, interactive examples, and depth of documentation, which sets the bar high for any developer tool.
Kubernetes
Kubernetes is one of the most popular container orchestration tools that is part and parcel of the DevOps world. Being this popular, it’s no surprise that Kubernetes boasts amazing documentation. The documentation home page is entirely made up of links to different sections, including a glossary and the process of how to contribute to Kubernetes. Each page of the documentation allows you to submit an edit to the documentation repository hosted on GitHub:
Kubernetes documentation is also one of the few documentation provided in multiple languages. You can choose over ten different languages to read the documentation in, which means language is no barrier, and developers from anywhere can make full use of the documentation:
The documentation website has an easy-to-understand layout. The Getting started guide provides a nice starting point, and each concept has its own section. You can also find complete tutorials of different use cases and scenarios in the Tutorials section:
Each concept is supplemented by adequate examples of necessary YAML files and kubectl commands:
Each section also has a What’s Next? section to guide you in exploring related features. The search features support fuzzy searching, but it doesn’t support autocomplete or autosuggestions. However, the search is still powerful enough to find what you need in most cases.
Overall, Kubernetes delivers solid multilingual documentation with enough examples and resources to make sure that you’re not left empty-handed.
Docker
Docker is undoubtedly a household name for developers all around the world. And you don’t become as popular as Docker without having superb documentation. The documentation is well-thought-out and structured in an easy-to-navigate manner. It is subdivided into guides, manuals, references, samples, and FAQ. The home page links to the installation guide so that someone who doesn’t have Docker yet can get started immediately:
You can also access different sections right from the home page:
Docker also takes advantage of its huge open source community by linking to community resources such as the forum and Slack channel:
Docker incorporates Algolia as the search engine, which offers a powerful search feature along with fuzzy searching and a keyboard-navigable search widget. You can use CTRL + K to activate the search and arrow keys to navigate:
When it comes to depth, it’s hard to beat the Docker documentation. A simple example is the installation guide for Docker Engine. Not only does Docker provide guides for different operating systems and platforms, but it also provides you with useful tips like post-installation steps and troubleshooting guides:
Docker provides thorough examples and explanations for all its features, including related environment variables, configuration files, and experimental features. The Reference documentation section is a goldmine for discovering every single property of the Docker CLI, Dockerfile, Compose file, and API. Finally, the FAQ section saves developers much time as it already answers common questions.
In conclusion, the Docker documentation is an example of an all-around solid documentation. A clean UI/UX, complete examples, and a nice FAQ section shine as its plus points.
Twilio
Twilio is a popular service that provides communication tools for making and receiving phone calls, texts, emails, and much more. The Twilio documentation clearly shows the amount of effort put into the tool to make it accessible to every developer. The documentation boasts a clear and modern design, with the home page showcasing different products. The documentation is offered in three languages: English, German, and Spanish:
Just like Docker, Twilio also uses Algolia to implement the search functionality. So you can rest assured you will find what you are looking for!
Each product provides an overview to give you a bird’s-eye view of what you can expect. You can find detailed examples and explanations in the left sidebar:
The API references are all accompanied by sample code in multiple languages and frameworks, such as Node.js, Python, and Java, along with sample responses and a detailed description:
The Tutorials section provides complete guides on different scenarios and use cases of the Twilio API, with the option to choose your favorite language:
Overall, the Twilio documentation does a good job of hitting it out of the park with complete examples, multiple languages and frameworks, and solid search functionality.
Vue
Vue is a JavaScript library for creating reactive and highly performant frontend UIs. The Vue documentation boasts a variety of contents, such as guides, tutorials, examples, quick starts, glossaries, and many more:
The accompanying code samples are complete, and all of them are followed by links to the Vue Playground, where you can experiment with the code interactively:
If you choose to go the Tutorial route, you’ll be presented with a step-by-step interactive tutorial where you can learn the ins and outs of Vue interactively:
The Vue documentation also uses Algolia to implement searching. Needless to say, it provides a solid site-wide searching experience with autosuggestions and fuzzy searching.
Overall, the Vue documentation does a good job of covering all the grounds and showing you the full power of Vue through an interactive playground.
Next.js
Next.js is a React framework for building full-stack web applications. Next.js has seen a boom in popularity, and there’s no surprise that it boasts great documentation. The Next.js documentation has a sleek, modern UI that greets you with a nice introduction that sets the stage for what to expect:
The docs provide a thorough tour of the features of Next.js, including routing, rendering, caching, components, and functions. You can choose whether you want to use the Pages Router or App Router:
A fast and snappy search widget is provided, which can also be activated by pressing CTRL + K. You get a documentation-wide search with the option to switch between the Pages Router or the App Router:
The code examples are complete and in-depth, with the option to choose between JavaScript and TypeScript:
Finally, if you click on the Learn button at the top, you’ll get access to a Next.js course that’s designed to take you from beginner to expert. Next.js also has guides on the Vercel site that explores many different scenarios where Next.js can be used.
The Next.js documentation is a solid work of art that blends a modern design with thorough resources and helps any developer learn the tool quickly and easily.
Google Cloud
Let’s face it, Google Cloud is a behemoth. With a product of that size, you’d expect the documents to be complicated. But Google has done a commendable job of keeping it organized. The home page immediately points toward the quick-start guides, tutorials, and code samples for those who are just testing the waters with Google Cloud:
For seasoned veterans, scrolling down reveals the list of documentation of every single one of the hundreds of products available in Google Cloud:
Each product showcases a collection of training materials and tutorials, use cases, code samples, and even videos:
The tutorials are clear, are in-depth, and link to appropriate pages in the console. With one press of a button, you are taken to where you need to be to follow along with the tutorial:
For codes and commands, you get the option to edit variables inline, which then replaces all occurrences of the variable in the rest of the tutorial, making it easy for you to copy-paste the code:
When it comes to search, it’s a no-brainer that Google dominates that field. This documentation is also no different. Google’s powerful search engine can fetch you hundreds of results in milliseconds:
However, Google takes its documentation one step further by incorporating role-based learning, a training hub, and certifications. This means that if you want to learn Google Cloud, their documentation is literally the best place for that.
The Google Cloud Services stand out from the rest by incorporating training programs and guides. It’s pretty hard to beat Google Cloud Services in terms of the resources provided.
Amazon Web Services
Just like Google Cloud, Amazon Web Services (AWS) is a giant in the cloud computing landscape. And just like Google Cloud, AWS also hosts hundreds of products, so you can expect the documentation to also be gigantic. Unfortunately, the AWS documentation is organized very confusingly, especially if someone has never used AWS before. If you go to the AWS home page and click on the Documentation tab, you’ll be taken to a page that seems daunting because it just has links to all the products and nothing else:
If you click on any of the links, you’ll realize that it’s not the full documentation but rather just an overview of that product:
That’s because the Documentation page is just a collection of overviews of different products. To find the actual documentation of a product, you need to find it from the Products menu and click on it to go to the product’s home page:
From there, you can click on Resources and then on Documentation to find the documentation:
However, where AWS lacks in user experience, it makes up for in terms of depth and usefulness. After all the work you did to find the documentation for a product, you’ll be rewarded because it’ll be all you need. Each product page has easy-to-understand overviews with diagrams, getting-started guides, use cases, and often, introductory videos.
The documentation is thorough, covering all possible ground, starting from setup and prerequisites, all the way up to advanced features, best practices, tutorials, and code examples:
The code examples provide options to choose your favorite language or framework, and you also get a mega repository of all code examples used in the documentation:
As for search capabilities, AWS offers a super powerful search engine that returns results from the documentation across all their products, blogs, and resources, as long as you search from the Overview page:
If you search from within an individual product’s documentation, by default, it’ll be scoped to that product only, but you can simply remove the filter to trigger a full documentation search:
AWS offers the ability to download each product’s documentation as a PDF so that you can store an offline copy or read it from your own devices.
Overall, AWS loses a few points on the UI/UX front but scores solid points for the volume and depth of the guides.
Heroku
Heroku is a cloud platform as a service that offers hosting applications written in a wide range of languages, such as Ruby, Node.js, Scala, and Go. The Heroku documentation home page starts with a prompt to select your programming language, along with links to some important language-agnostic features, such as the Heroku CLI, Heroku CI, and logging:
For each language, they offer a quick-start guide that starts from the setup and takes you to the full-fledged app deployment on Heroku:
Each quick-start guide has an accompanying sample application that you can clone from GitHub:
You can log into Heroku and save your progress in the quick start. This means you don’t need to finish the quick start in one go, and you can learn at your own pace.
Apart from quick-start guides, Heroku has in-depth documentation on other features, such as the CLI tool, continuous integration, continuous delivery (CI/CD), database, monitoring, add-ons, and security and billing.
The search feature of the Heroku documentation is very good. It doesn’t have autocomplete or autosuggestion, but it can search through the documentation, marketplace, blog, and the whole of the Heroku website:
For non-English-speaking developers, Heroku docs are also available in Japanese.
The Heroku documentation shows how you can create good documentation with a minimal and clean UI while still delivering enough content. Although it doesn’t have an interactive playground like Vue, it is in no way less resourceful.
Vercel
If you were impressed by the Next.js documentation, wait till you see the Vercel documentation. Since Vercel is the company behind Next.js, it’s no surprise their documentation feels very similar to the Next.js documentation in terms of UI and aesthetics. At first glance, they both use a similar design and UI elements, like cards, buttons, and a sidebar:
Vercel provides a Get started with Vercel guide that gives you an overview of the process that you need to follow to deploy your app on Vercel. Vercel provides framework-specific documentation, such as Next.js, SvelteKit, and Remix. You can deploy an app straight from the documentation by clicking on the Deploy buttons, or you can choose a template:
The code snippets show an option to switch between JavaScript and TypeScript. The code snippets also have line highlighting, which makes it easy to draw attention to particular lines of code. Each snippet is accompanied by a file name, line numbers, and a Copy button to make your life easier:
Each page also has a More Resources section so that you can follow up on what you learned by using it in a real-life scenario:
Finally, searching in the Vercel documentation is similar to Next.js, except you get an option to search within the Vercel docs, the Next.js docs, the Turborepo docs, or through everything:
The Vercel documentation, just like Next.js, has a great combination of good UI and content that delivers immense value to the developer.
Netlify
While on the topic of cloud platform-as-a-service providers, don’t ignore Netlify. Netlify is used by big companies, such as Google, Twilio, and Peloton, to deploy their web infrastructure. The Netlify documentation greets you with a minimal and sleek modern design, with links to Netlify products and a sidebar menu:
The docs cover a wide range of topics, starting from a quick-start guide to advanced features, such as the Netlify CLI. The guides are accompanied by code snippets and video tutorials wherever possible:
The guides do a great job of explaining the topics in detail, and if you still feel like you’re stuck, you can send them feedback about the docs directly from the page:
The search widget of the Netlify documentation does a great job of finding the relevant information quickly and accurately. The search bar supports autosuggestion and fuzzy searching:
However, one area where Netlify excels is the Ask Netlify feature. It’s an integrated AI chatbot that you can ask questions, and it’ll find you the answers based on the product documentation, support forums, blogs, CLI documentation, and API documentation.
Netlify goes one step further by incorporating an AI chatbot into the documentation. With the advent of AI, incorporating it is a big step toward an excellent user experience. However, even without the AI chatbot, Netlify documentation holds great value for any developer with its tutorials, guides, and examples.
Tailscale
Tailscale is a VPN service that lets you access your devices and services from anywhere in the world. Tailscale boasts simple but thorough documentation. It doesn’t have the super modern design that some of the other entries in this list have, but it makes up for that with the content:
The Tailscale documentation covers a wide range of topics and explains all its bells and whistles. The guides are super thorough, with lucid explanations, along with screenshots and internal links:
Where needed, code snippets are provided. The snippets lack line numbers, but they have syntax highlighting, and comments are used to explain different parts:
The search widget supports autosuggestion, and it can show you results quickly. However, it doesn’t support fuzzy searching:
Tailscale does a fantastic job of packing a punch within a clean and minimal UI. The documentation is solid, explains all features, and goes into in-depth explanations.
Conclusion
Documentation can make or break your product. Good documentation is the key to retaining developers and onboarding new ones. In this article, you looked at twelve of the best documentation out there. You learned what makes them great and, hopefully, got some ideas for improving your existing documentation or creating new ones.
TL;DR: Improve your technical documentation with these 6 proven strategies:
Scannable Navigation – Use clear hierarchies and breadcrumbs to reduce cognitive load
Plain Language – Eliminate jargon while maintaining technical accuracy
Audience-Specific Depth – Tailor content from beginner tutorials to advanced docs
Visual Elements – Increase retention rates using diagrams, examples, and interactive elements
AI-Assisted Workflows – Use AI tools to accelerate drafts and flag outdated content, with human review at every stage
Agile Cycles – Maintain accuracy and relevancy by reviewing and updating periodically
Ever felt puzzled by a confusing error message, found yourself testing a new software program with difficulty, or wished for a simple guide to understand the instructions for your latest gadget? If you have, then you’ve experienced the world of technical documentation, and it can be frustrating.
Technical documentation refers to comprehensive written guides and materials that explain the design, development, and usage of a system, software, or product, facilitating understanding, troubleshooting, and maintenance for users, developers, and other stakeholders.
Why is this important? Whether you’re someone who knows your way around technology, a junior dev figuring things out or someone who is just trying to keep up with the digital world, clear technical documentation is crucial for your success. It gives you the tools to understand new tech, solve issues, and make the most out of the products and processes you encounter.
In this article, you will learn the different types of technical documentation, explore their applications, and walk away with essential tips for crafting your own user friendly technical guides.
Technical documentation serves as the bridge between complex systems and the people who interact with them. It’s an umbrella term that covers any written material that explains the functionality or inner workings of a product, service, or process. Technical documentation is written by technical writers in collaboration with subject matter experts (SMEs), and it comes in various forms:
Project documentation: Consists of plans, specifications, and reports that track a project’s development, like software development lifecycle documents or engineering blueprints. It is usually meant for internal use of an organization’s teams.
Product documentation: Aimed at the end user, offering guides, tutorials, and FAQs that explain how to operate and troubleshoot a product, such as user manuals for smartphones or software help files.
Process documentation: Outlines standardized procedures for internal operations, like quality control checklists or training materials.
The quality of technical documentation can greatly impact the user experience and productivity, irrespective of whether these users are your external customers or internal employees. Here are a few other reasons why you should focus on creating good technical documentation:
Empowers users and developers: Clear instructions enable users to maximize product potential and equip developers with the knowledge to maintain and improve it.
Boosts efficiency and collaboration: Easily accessible documentation reduces time spent on explanations and enables seamless teamwork.
Documents internal knowledge: Documented decisions and processes build a historical record that is valuable for future reference and training.
How to Write Good Technical Documentation
Now that you understand what technical documentation is and why it’s important, it is time to learn some of the ways in which you can improve the quality of your technical documentation. This section will not go into the basics of how to write technical documentation but rather focus on some key tips you can use to improve the quality of your technical documentation.
How Do You Create an Easily Navigable Structure for Technical Documentation?
Technical documentation structure organizes content from general concepts to specific details using a table of contents, descriptive headings, and internal navigation so users locate information without reading the full document.
The first thing any reader would notice when they come across your technical documentation is its structure. It is usually not possible for a reader to go through the entire documentation for a product or service to find what they are looking for, so having a structure that is easy to navigate and allows convenient searching of commonly used concepts or pages becomes very vital.
Research from the Nielsen Norman Group (NN/g) shows that well-structured navigation and scannable headings significantly reduce cognitive load.
There are other benefits of keeping a simple, easily navigable structure for your technical documentation:
Reduced cognitive load: A well-organized document minimizes the mental effort users have to apply to search for information.
Improved findability: Clear headings, subheadings, and navigation elements direct users to specific sections quickly.
Enhanced scannability: Readers can easily skim the document to grasp its overall flow and identify relevant sections.
Increased engagement: Users are more likely to persist and complete tasks when they can find what they need easily.
Some changes you can make to your document’s structure to improve it include the following:
Clear table of contents: Provide a comprehensive overview of the document’s content and hierarchy.
Informative headings and subheadings: These act as anchors, guiding users to relevant sections.
Logical hierarchy: Information should be organized progressively, from general concepts to specific details.
Strategic use of formatting: Set in boldface key terms, use bullet points for lists, and use white space strategically to improve readability.
Integrated navigation elements: Use breadcrumbs, sidebars, and internal links to allow users to jump to different sections easily.
The Firebase documentation is a great example of a good structure that makes it possible to navigate through a huge knowledge base easily. The entire documentation for all products is first categorized based on the purpose of the services (ie app development, release and monitor, or engagement):
Then as you go into each category, you find detailed docs arranged based on the individual services and the platforms that they work on:
Without such a hierarchy, it is very difficult to find what you’re looking for when you’re working with one of the many Firebase services.
How Can You Make Technical Documentation Accessible and Easy to Understand?
Accessible technical documentation uses plain language, active voice, and defined terminology so readers at any technical level can follow instructions without specialized prior knowledge or repeated re-reading.
Technical documentation usually consists of information that is entirely new to its target audience. In this case, it becomes all the more important to present the information in a way that allows readers to understand it easily. Excessive use of tech jargon and complex language can make it difficult for new readers to quickly read and grasp the concepts.
Here are a few key points you can keep in mind to make your technical documentation simpler:
Use plain language: Avoid overly technical terms and opt for everyday equivalents. For example, replace utilize with use and parameterize with set.
Embrace active voice: It makes your writing more engaging and easier to follow. For example, instead of saying “The button is to be clicked,” say “Click the button.”
Define key terms: Introduce and explain technical terms the first time they appear. Consider using a glossary for quick reference.
Write concisely: Focus on essential information and avoid unnecessary details. Remember, less is often more.
Collect feedback from real users: Get feedback from people who represent your target audience. Their perspective highlights areas needing simplification.
How Do You Ensure the Right Level of Depth in Technical Documentation?
Documentation depth is calibrated to audience expertise using user personas; beginners need step-by-step context, intermediate users need troubleshooting guides, and advanced users prefer concise technical references without foundational explanation.
Customizing your content to your audience’s specific needs and knowledge level is crucial for creating clear and impactful documents.
According to Usability.gov, developing user personas helps align documentation with real-world user needs, improving clarity and reducing misinterpretation.
This approach enhances the quality and effectiveness of your writing, ensuring it resonates with the audience and serves its purpose effectively.
Tailoring the writing style and depth to your audience’s understanding prevents confusion and frustration. Beginners require more explanation and context, while experts appreciate conciseness and technical details. Providing the right level of detail saves users time and effort, allowing them to quickly find and apply relevant information.
To do this, you need to first know your audience. Start by defining user personas and creating profiles representing different user types. Then conduct surveys, interviews, or usability tests to understand their needs, expectations, and technical knowledge. You could also look at user support tickets, forum discussions, and app analytics for insights into the user challenges and information needs.
Once you have a clear idea of who your audience is, customize your technical documentation to their technical understanding. Here’s a quick list of tips to help you get started:
Beginners: For beginners, focus on basic principles, provide step-by-step instructions, and clearly define technical terms. Be generous with visuals like screenshots and diagrams to enhance understanding.
Intermediate users: For a more experienced audience, offer more detailed explanations, introduce relevant technical vocabulary, and provide troubleshooting guides for common issues.
Advanced users: If you’re aiming for an advanced user base, you can assume prior knowledge, delve into complex technical details, and offer reference materials for further exploration.
In some cases, it might be hard to put your audience in just one of these categories. The Twilio documentation is a great example of this case. Twilio’s users encompass all technical levels, so Twilio provides a detailed glossary of concepts while offering interactive tutorials and guides to help everyone get started at their preferred pace:
The key is to know your users.
How Should You Include Examples, Visuals, and Interactive Elements?
Visuals in technical documentation increase comprehension by offering alternative ways to process information; diagrams explain spatial relationships, screenshots orient users, and interactive tutorials reinforce learning through practice rather than passive reading.
Technical documentation can often feel like a text-heavy slog, stranding readers in a sea of words. That’s where visuals, examples, and interactive elements become crucial. They aren’t just there for decoration; they’re powerful tools that can turn your documentation from boring to interesting, making it easier for readers to understand and remember the information.
Educational psychology research, including Richard E. Mayer’s Multimedia Learning Theory, shows that combining visuals with text can increase comprehension and retention significantly
Visuals and interactivity in technical documentation can help in catering to different lifestyles. As not everyone learns best by reading, visuals, like diagrams, screenshots, and videos, can explain complex concepts more intuitively, appealing to visual learners. More often than not, a wall of text can be intimidating.
Integrating visuals creates interesting breaks, making the document more scannable and engaging. Interactive elements like quizzes, simulations, and clickable tutorials allow readers to experiment and learn by doing, solidifying their understanding. Therefore, you should consider using visuals, examples, and interactive elements in your technical documents.
Remember not to overdo it. Always make sure that your visuals and interactive elements directly relate to the content and enhance understanding. Invest in high-resolution images and clear diagrams. Blurry or poorly designed visuals can hinder comprehension. When working with visuals, ensure all of them have alt text for screen readers and consider color contrast for visual impairments. Interactive elements should engage, not overwhelm. Always balance their complexity with the target audience’s skills.
The Stripe documentation is one of the best examples of using interactive and visual elements to the fullest while not overdoing it.
For instance, their Quickstart page on Stripe-hosted payments features a follow-along tutorial with interactive code blocks and preview windows to help you visualize what your integration’s final result will look like right on the documentation page itself:
Building such documentation requires great effort, but it pays as well. The key is to understand how your document can benefit from visual and interactive elements and make use of them effectively.
How Can AI Tools Enhance Your Documentation Workflow?
AI documentation tools accelerate first drafts and flag inconsistencies across large doc sets, but require human review for technical accuracy, security considerations, and brand voice — according to Draft.dev’s annual developer marketing survey in 2026, only 7% of teams rate them “very useful” without human oversight.
The documentation landscape has shifted dramatically since this article was first published in 2024, so we added this section to cover the rise of AI in the developer space. In 2026, AI-powered tools play a meaningful role in creating, updating, and maintaining technical documentation, though human oversight is completely essential for accuracy and brand consistency.
According to McKinsey’s State of AI 2025 survey (conducted June-July 2025 with nearly 2,000 participants across 105 countries), 88% of organizations now report regular AI use in at least one area, up from 78% the previous year. The same survey found that knowledge management has become one of the functions with the most reported AI use. Documentation teams are increasingly using these tools for certain tasks within their workflows.
Where AI tools add value in documentation:
As confirmed in Draft.dev’s Developer Marketing Survey 2026, AI’s main use case so far is generating initial drafts from code comments, API specifications, or meeting notes. They’re great at identifying inconsistencies across large documentation sets and suggesting improvements for clarity and readability. Tools like GitHub Copilot can auto-generate docstrings, inline comments, and basic documentation directly within your IDE. According to GitHub’s documentation, Copilot can analyze code context to generate meaningful comments and explanations, helping developers understand complex logic and hidden dependencies. Platforms like Mintlify take this further by monitoring codebases and automatically proposing documentation updates when code changes ship.
Where human expertise remains critical:
AI-generated content requires careful review for technical accuracy. The McKinsey survey noted that only 54% of organizations have defined processes to determine when AI outputs need human validation, and in Draft.dev’s survey, only 7% found AI “very useful” in their workflows thus far. Complex architectural decisions, security considerations, and edge cases need human judgment. Style consistency, brand voice, and audience-appropriate tone still depend on experienced technical writers. AI tools may introduce errors or outdated information that only subject matter experts can catch.
Best practices for AI-assisted documentation:
Use AI tools for first drafts and repetitive tasks, then refine with human expertise. Implement review workflows that verify AI-gen content against actual product behavior. Maintain style guides that AI tools can reference for consistency, but beware that even if you try to cover your bases, it can still “forget” or get things wrong. Keep humans in the loop for final approval, especially for customer-facing documentation.
The emerging trend of “agentic AI” workflows, where multiple AI agents handle different aspects of documentation (research, drafting, review, testing), is gaining traction. McKinsey’s survey found that 62% of organizations are at least experimenting with AI agents, and 23% report scaling them in at least one function. However, teams adopting these approaches emphasize that clear governance, human oversight, and quality control processes remain non-negotiable.
Why Is It Important to Periodically Update Technical Documentation?
Periodic documentation updates keep instructions aligned with a product as it evolves; outdated docs increase support costs, erode user trust, and create confusion that accurate, regularly reviewed content prevents.
Creating technical documentation isn’t a write-it-once-and-forget-it task. Agile methodologies emphasize iterative improvements, and ISO 9001:2015 (Quality Management Systems) requires documentation to remain accurate and up to date.
Outdated information in technical documents leads to confusion, frustration, and wasted time for users. Updating ensures that users have the right instructions and procedures at their fingertips. Additionally, new features, bug fixes, and changes in workflows need to be reflected in the documentation for users to stay on top of things. Regular updates demonstrate your commitment to maintaining high-quality resources and building trust and credibility with users.
To make sure you’re updating your technical documentation effectively, here are a few tips you can follow:
Establish a schedule: Set a regular review and update cycle based on the pace of change in your product or process.
Use version control: Implement a system to track changes and maintain previous versions for reference.
Seek user feedback: Actively look for feedback from users about outdated information or areas needing clarification.
Apply small, focused updates: Break down updates into manageable chunks, addressing specific changes rather than rewriting the entire document.
Integrate with development pipelines: Modern documentation tools can monitor code changes and flag outdated documentation, reducing manual oversight.
Conclusion
This article covered what technical documentation is, its various types, and its practical use cases. You also learned handy tips on how to create effective technical documentation, including how to leverage AI tools while maintaining quality through human oversight.
TL;DR: How Draft.dev uses AI writing tools in technical content production:
What We Use AI For: Generating article descriptions, title variations, content outlines, email replies, and brainstorming list items and transitions
What We Don’t Use AI For: Writing actual technical content, replacing subject matter experts, or creating content requiring deep technical expertise and personal experience
Quality Control: Human experts must guide and fact-check all AI output, with detection tools to identify AI-written content in submissions
Future Vision: AI writing tools will function like Excel for accountants—augmenting expert work rather than replacing it, making writing more approachable for engineers
Great writers won’t be replaced by AI but will learn to work with it as a virtual assistant to increase productivity.
It’s interesting to compare the two videos because you can see how much better these tools got in just a year. That said, all the tools I tried in 2020 and 2021 were clunky. They seemed to push in the direction of writing entire blog posts for you, but they couldn’t get beyond surface-level definitions of terms and often introduced factual inaccuracies.
In 2022, OpenAI released Chat GPT, and by early 2023, it had hit the mainstream. Everyone from clients to writers to family members asks me about AI writing now, so I thought it would be worth putting down a short summary of my thoughts and the role we see these tools playing at Draft.dev.
TL;DR: We believe in embracing new technology and learning how to use it.
In their current state, AI writing tools cannot replace the writers we work with (engineers with deep subject matter expertise), but we are exploring these tools and how using them could make sense.
How do AI writing tools like GPT actually work?
The well-known generative writing tools available today (like GPT-3 and more recently, GPT-4) use large language models (LLMs) to summarize or generate text based on existing text datasets. In other words, they “read” content on the internet and use it to surmise patterns that allow them to write new content.
LLMs are a form of neural network, a concept that’s been part of machine learning for at least 40 years, but the big unlock in recent years has been cheaper access to computing power and storage. While it’s not trivial to crawl enough of the internet to build one of these things, Google’s been doing it since 1996, and as you might imagine, they’re not the only ones gathering data.
As the ability to collect and store text data improved, so did the availability of computing power to compute the strength between nodes in this data. The technical details go beyond my understanding, but essentially, LLMs today are trained on trillions of words to calculate the relationship between them and “learn” to use them.
What can AI writing tools do well in 2025?
This technology is changing (and improving) rapidly, but as of March 2023 when I write this, the best general-purpose consumer-available AI writing tool is OpenAI’s GPT-4 (the model used by Chat GPT).
It can do amazing things like write a short poem about the recent collapse of Silicon Valley Bank in the style of Charles Bukowski:
The Valley once glittered with gold,
But greed took hold, and fortunes were sold.
Silicon dreams turned into a nightmare,
As the bank collapsed, leaving despair.
Investors panicked, accounts were drained,
The system failed, and hope remained.
Bukowski saw it all before,
The rise and fall of money's allure.
The Valley's tech giants brought hope and change,
But the price we paid was out of range.
The crash of '23 was a bitter pill,
And the wounds may take years to heal.
But in the rubble, we'll rebuild anew,
The spirit of innovation shining through.
Lessons learned, the future bright,
As we rise again with all our might.
Or describe the feeling that an ancient Greek stoic would have while falling off a cliff:
I strive to maintain a state of inner calm and rationality regardless of external circumstances. Therefore, as I fall off a cliff, I focus on accepting the inevitability of my fate rather than giving in to fear or panic.
I remind myself that death is a natural part of the cycle of life, and that my consciousness will simply return to the universe in a different form. I reflect on the impermanence of all things and the idea that my time on this earth was always limited. I find solace in the knowledge that I lived a virtuous life, true to my principles and values.
As I approach the ground, I feel a sense of detachment from my physical body and a deep sense of peace. I trust that the universe has a plan for me, and that whatever happens next is simply part of that plan. In this moment, I am at peace with my fate, knowing that I lived and died according to my own code of ethics.
What AI Writing Doesn’t Do Well
But it’s not perfect. The current iteration of GPT-4 isn’t updated with real-time data (although that’s coming soon), and it often states factual inaccuracies confidently without citing sources, so it’s essential to have a human in the loop.
AI experts caution, however, that such tools should only be used to support people who are already experts in their domain. Generative AI has been shown to spew disturbing content and misinformation, while other concerns have surfaced over intellectual property theft and privacy. – Karen Hao, The Wall Street Journal
It also doesn’t do well with personal experience or realistic examples, especially in niche topic areas (like ours). While you can try to push it to do so, it doesn’t always understand “real life” so it struggles to replicate the human experience.
Finally, it doesn’t do well with extended pieces of text. It struggles to go deeper into topics, so you’ll often find it repeating the same surface-level definition of a topic or spitting out nonsensical jargon because it doesn’t have enough good data on a particular niche.
For these reasons, it struggles at technical depth—one of our main selling points to clients—and it’s nowhere close to replacing our world-class group of software engineers as a writer. As a rule, we push writers to go deeper and add more personal experience when we see it lacking, and we’re planning to use Positional to detect AI-written content going forward.
What AI Writing Does Do Well
That said, we are starting to use GPT-3 in a few specific ways.
We’ve started using it to generate short descriptions of new articles, new variations of titles for blog posts, and even some article outlines. While we still have to guide and fact-check the machine, it’s saving us a few hours of work per week already.
Coworkers have told me they use it to reply to emails, come up with definitions for generic terms, and get started on new ideas. While I haven’t found it useful for writing the actual content of a blog post, it has helped me come up with ideas for items in a list or brainstorm transitions between sections.
Many of GPT-3’s weaknesses are fixable though, so I think we’ll continue using it more in the future. It’s pretty easy to imagine OpenAI including fact-checking and real-time data in future models. Other companies will also be building specialized versions of OpenAI’s generic language models to work better for internal docs, emails, and industry-specific writing. It’s going to be a very interesting next few years in the writing industry.
How will AI writing tools change content marketing?
AI writing tools will be for writers like Excel is for accountants.
Great writers (like great accountants) won’t be replaced by AI writers, but will instead learn to work with AI as a virtual assistant to get more done.
Subject matter experts with personal experience and knowledge of the nuance of their field won’t be replaced by AI, but maybe the tools will make writing more approachable. I’d love to see more engineers start writing because tools like Chat GPT make it easier.
Generative AI might also change the way we search for information online. We may be able to interact with search engines through more natural formats like asking questions, and maybe…just maybe…Siri will finally be good at something.
Like Ryan Law recently said, anyone working in content marketing or writing today should be exploring these tools and learning how to use them in their day-to-day. I’d love to hear how you’re exploring and using AI in your writing. Find me on Twitter to continue the conversation.
TL;DR: Refreshing old blog posts increases organic traffic through strategic updates:
Remove irrelevant content with little traffic to boost overall site quality
Merge similar posts to consolidate authority and eliminate redundancy
Update high-ranking posts with fresh data, improved keywords, and better media
Build internal links between related content to strengthen topical authority
Republish and re-promote updated posts to gain immediate traffic boosts
This case study shows real results from refreshing a technical blog over six months, including specific traffic increases and proven methodology.
When I left my role as a startup CTO to found Draft.dev, I decided I would invest a little time improving my personal blog. I’ve been writing sporadically on the site for the past decade, but before 2020, I wasn’t consistent, and the topics varied widely. As I began writing technical content full-time for clients and learning more about SEO, I decided it was time to make some updates to my personal blog as well.
Why Refresh Old Blog Posts?
One of the easiest ways to improve an existing website is to improve the content that’s already there. Because you don’t have to start from scratch, you’ll spend less time on each piece of content, and if (like me), you didn’t pay much attention to SEO or keywords or length when you wrote the piece initially, you might get a big lift out of the effort.
My blog has been around for a long time, so it has some domain authority, and a few posts rank well in Google. Still, many of the posts that I thought were good had almost zero search traffic, and some of the ones that had good search traffic were not relevant to my audience. I had also published 200-word summaries of articles that I wrote for other websites, and those were getting zero traffic and likely hurting my standing in search engines.
The goal of refreshing my blog was to increase the amount of traffic I got from search engines and gain more email subscribers to my newsletter each month. In this post, I’ll show you how I am doing this and what the results have been so far.
The Challenge in Keeping a Technical Blog Up-to-Date
My blog contains a mix of developer tutorials, opinion-driven technical thought leadership pieces, and collections of books and tools I find useful. While most of the posts written in the past couple of years weren’t too bad, many of the older posts are now full of deprecated references and technologies.
Blog posts will suffer in search engines if they get out of date or factually inaccurate. If you write a lot of tutorials, this can make keeping your blog relevant incredibly hard. You might spend half your time just keeping old posts updated.
Planning My Approach To Refresh Blogs
In deciding how I would go about the content refresh project, I ran across two compelling case studies that serve as good examples of successful refreshes. These served as inspiration and gave me enough information to plan my content update.
While many SEO case studies show how to increase your traffic to rank new websites, there aren’t as many available where people talk about how they recover penalized websites.
In this article by Servando Silva of Stream SEO, the author walks you through a site he helped recover from a Google penalty. By removing low-quality content, beefing up existing posts, and removing problematic backlinks, Silva increased the nearly dead site to more than 6,000 visits per month.
My blog didn’t have the spam backlinks problem that Silva’s did, but I did have some low-effort content that needed to be removed or improved.
Another area of search engine optimization I had never paid much attention to was keyword optimization. Pkwy Digital’s problem was similar in that they had lots of posts that ranked in the 6-10 spots on Google but very few in the top 5.
Those coveted top 5 spots are where almost 70% of the clicks land, so if you can bump the ranking of a post in the bottom 5, you can make a significant impact on your post’s performance in Google. After making some keyword optimizations and combining similar posts, Pkwy increased their average search engine clickthrough rate from 1.8% to 4.9%.
That means that if they were getting 100,000 monthly search impressions, they would have gone from 1800 monthly visits to 4900. That could be huge for a small site like mine that was getting 1500 pageviews a month from search engines.
Five Methods to RefreshBlog Posts
Armed with these two case studies and ahref’s fantastic guide on refreshing blog posts, I set out to start improving my blog. Here are the five tactics I used in various cases to update my old blog posts:
1. Remove Irrelevant Content
Following ahref’s suggestions here, I looked through all 200 posts on my blog and found all of them that were receiving little to no traffic. Of those, I removed and redirected any that were off-topic, very short (<500 words), or about old technology that was no longer relevant.
A few posts that got very little search traffic still performed well on social media, so I decided to keep them around for possible updates later. Of the posts I removed, I redirected most to the homepage using a Cloudflare Worker. A few posts that got little traffic were similar to another, so I redirected them to the other article.
By removing this irrelevant content, I’m showing Google that a higher proportion of my content is high-quality. This will lead to an overall increase in site reputation over time as Google registers the changes.
2. Merge Redundant or Similar Posts
I had written four blog posts about my process for hiring software engineers. The first mentioned a specific job posting that had long since expired, the second told how I was revising my hiring process, and the third and fourth told the results of these revisions.
While having multiple posts about similar topics isn’t bad, I felt like there wasn’t enough unique content in each post to justify having four of them. Plus, some of the information was out of date and no longer helpful.
So, I took all four posts and merged them into the URL with the most backlinks and search traffic already (which happened to be the oldest one). This new post is essentially a complete rewrite, although it uses pieces of each of the original posts. It’s much longer but broken into scannable sections so that readers can easily jump to the parts they need.
3. Update Existing Posts That Rank Well
In 2015, I wrote a post about how I spent my time as an engineering manager. After tracking my time every day for months, I gave readers detailed insight into a day in the life of an engineering manager.
This post has done pretty well in search engines, ranking for a few terms that are very relevant to my blog’s audience. Unfortunately, even good blog posts tend to degrade over time, so by 2020, much of the luster had faded. I figured I would try to update the post to restore a bit of its former glory.
Here’s what I did to improve posts that already ranked pretty well but needed a refresh:
Update technical details and add more relevant sections.
Ensure relevant low-competition keywords were present in headings.
Improve the introduction and meta description to boost clickthrough rate.
Each post I update is more current, longer, and more likely to jump back up in the search rankings after the refresh.
4. Build Internal Links
Another series of posts that performed okay in search engines were all related to software testing. Unfortunately, none of the posts linked to each other. While internal links don’t count for as much as external links do, they still help ensure Google knows which pieces of content might be related and they encourage readers to visit more pages.
I looked through all the posts on my site and added categories. Then I looked for opportunities to link relevant posts to each other. I doubt this will dramatically improve my search rankings alone, but it’s not a bad idea.
5. Update Post Dates and Re-Promote
Finally, after I updated each post, I updated the published date and put it through my technical blog post promotion checklist again. I had promoted these posts once when they were first published, but that was years ago. After refreshing them, the content was different enough that promoting them again seemed like an easy win.
In the case of my post on A Day in the Life of an Engineering Manager, sharing it led to an additional 728 visitors to a post that was originally posted five years ago!
By the way: if you’re asking yourself ‘how old is my blog post?,’ it has probably been too long since you’ve completed a content audit. If you don’t have time to do this yourself, tools like Content Audit Tool (CAT) can help.
Results of the Refresh Blog Campaign
As of this writing, I’ve only updated a handful of my blog’s old posts, but I can already tell that the refreshes are having an effect. Here’s an example of the traffic to the Engineering Manager post I mentioned above:
The orange line is the traffic to the post between October, 12 and October 31st while the blue line shows what happened to traffic after I refreshed the post on November 1st. There were a couple of spikes when I shared it out on social media, but the baseline search traffic also rose.
This chart shows pageviews from Google before and after the refresh blog process:
While not much time has passed, it looks like Google is showing more people this article or clickthrough rates have gone up dramatically. I’ll have to dig into Webmaster Tools to be sure.
This increase in search traffic isn’t just limited to one post. Organic search traffic is up 61.9% on the site since I started this refresh effort in June.
Six months is not enough time to see the full effect of an update like this that’s still ongoing, but it does seem to suggest that refreshing old blog posts will work. I’ll report back on this as I continue to refresh my blog’s old content over 2021, so hopefully, we’ll have a more complete picture then.
If you’d like any help creating or refreshing content for your blog, book a call with me. I’d love to help you out or just walk through the process with you.
TL;DR: Most technical writer applications fail due to avoidable resume mistakes:
Critical requirements – Include published writing samples, demonstrate baseline software development experience, and eliminate all grammatical errors
Technical accuracy matters – Verify tool names, code snippets, and documentation links are correct to prove research capabilities
Customize for each role – Tailor your CV to match specific job requirements and showcase relevant domain experience
Avoiding these red flags puts you in the top 5% of applicants. If you lack published work, create 2-3 quality articles on Medium, DEV, or your own blog before applying.
Landing your first few technical writer jobs isn’t easy. Technical writing positions require strong software development skills and strong writing skills, and not all applicants are going to have both at the level that growth marketing managers need.
But, in my experience reviewing new technical writer CVs, a large number of applicants squander their chances by not presenting themselves in the best light. Most applications are disqualified by the presence of a few common red flags. These include, for example, the quality of writing displayed in the CV and in the pieces of content offered as writing samples.
This article will list the most common technical writer red flags that you should try to avoid. If you can prevent these problems from appearing in your resume, you should easily land among the top 5 percent of applicants.
Lack of Technical Skills
One of the biggest red flags to potential employers is a lack of technical expertise. Most employers want a technical writer who has software development experience, preferably in the domain of the company. The good thing is that this experience doesn’t need to be extensive. Internships, open source work, and hobby projects may give you enough qualifications for the recruiter’s needs.
Still, don’t worry if your technical skills don’t exactly match up with what the company wants—for example, if you’ll need to cover a frontend development technology like React but you’re experienced with Vue.js, or if you’re experienced in video streaming but you’re applying to a company that’s building a SaaS application.
As long as you have a baseline of familiarity with software development, the specific technical skills can usually be learned on the job, and most recruiters know that. If the rest of your resume looks great, the company shouldn’t mind taking the time to get you up to speed with the technologies.
No Previously Written Work
If there’s one thing that your future manager or editor is looking for in your CV, it’s examples of your writing. Even if your other articles aren’t in the area you’re applying to work in or if you don’t think your articles are impressive, the best way to prove that you can perform as a technical writer is to show that you have published work.
If you don’t have any articles or posts published yet, be proactive. It’s a good idea to create a few quality articles on your own and post them on websites like Medium, DEV, or your own blog. To enhance your work and make the best first impression, you can hire a freelance editor to go through your writing samples. You may find that the reward is worth the expense.
Typographical and Grammatical Errors
As a technical writer, you’re expected to care about the fine details of your writing. And if a technical writer’s resume has misspellings, poor punctuation, or grammatical errors, this points to one of two things: either the writer doesn’t care enough to make the resume look good, or the writer isn’t capable of doing so. Both usually lead to instant rejection by the hiring manager.
Most spelling, grammar, and other mistakes can be easily solved by using a typing assistant tool like Grammarly, so take the time to run it or a similar tool on your CV and example pieces.
Incorrect Technical Details
Though it’s important that you write well and steer clear of general errors, that alone isn’t enough. You also need to ensure that the technical details you include are accurate. If the name of a tool is misspelled, it calls your research into doubt. If a piece of code is incorrect in the smallest way, readers won’t be able to follow your tutorials. And if you include incorrect web links, readers won’t be able to find the documentation you’re citing.
Understandably, the person looking at hiring you will be watching for any slipups in this important area.
Mismatched CV
When you apply for a position, you should adjust the wording in your CV to match the exact needs of that position. Different companies will be looking for different skills and qualities in their new hires. If you showcase that you have the skills or qualities that the company is looking for, you can give yourself an edge over other candidates, many of whom will send their resume to multiple companies without changing the wording.
If you have experience working in the same field as the company, even if it’s not as a technical writer, make sure to include it. For example, if you are applying to a video streaming service provider and you have user-side experience streaming on Twitch, you’ll have an advantage since you’ll be able to better grasp the problems that users may encounter.
Customizing your CV enables the hiring manager to quickly check it for the information they need, and it demonstrates that you’re willing to go the extra mile for your job—a quality valuable to any business.
Lack of Career Progress
In most cases, good employees rise to higher positions in their companies. If you stay at the junior level for a long time, this signals that you either can’t or are not willing to perform at a more senior level. A potential new employer may see this as a red flag, as it could indicate that you don’t have enough expertise in your stated topic to write about it effectively or that your work ethic is lacking.
Unfortunately, if you’re already in this position, there may not be much that you can do. Your best option is to demonstrate that you’re in the mindset of always progressing in your role by listing what you’ve learned or explaining how you’ve improved on the job recently.
Unprofessional Email Address
While a lighthearted or silly email address is not the deal breaker that it might have been a few years ago, your email address still contributes to the overall impression that people form about you as they read your resume. If you want to appear professional, keep the address simple—first and last name, and nothing more if possible.
Unnecessary Information
Your resume should contain only the details that are most relevant to the specific company and job that you’re applying for. Other personal information is off topic and could potentially be harmful to list here, such as your political affiliation, your hobbies, or any unrelated skills.
Of course, hobbies that are relevant to the job—such as leading a software development book club or running a tech channel on YouTube—could make the difference in whether you get a job offer. Just be sure that such activities are connected with some tangible output, as many people in tech participate in these kinds of activities.
Conclusion
This list of red flags may seem extensive, but ultimately, the path towards a great technical writer resume is not that hard. Your resume must offer proof of your technical skills and include well-written tech content pieces, and it must look tidy and professional. The story it should tell about you is that you’re hardworking and always ready to improve. If you can accomplish these goals, you’ll put yourself ahead of the competition.
If you’d like to strengthen your resume with great pieces of tech content, you should apply to write at Draft.dev. We publish your articles under your own name, letting you add to your portfolio and boost your writing career.
TL;DR: Breaking into technical writing requires three core skills and strategic portfolio building:
Essential skills: Technical aptitude in your field, clarity of thought for complex topics, and understanding your target audience
Portfolio building: Start with personal blogging on platforms like Medium, Dev.to, or Hashnode, then volunteer for open-source projects
Landing paid work: Apply to Community Writing Programs, leverage LinkedIn networking, pitch publications directly, and explore platforms like Draft.dev
Technical writing is learnable through practice. Focus on topics you know deeply, write consistently, and share your work to build visibility and credibility.
I’ve enjoyed writing since my college days, when I lived with a bunch of English majors. In the 10 years I spent as a software engineer, I maintained a blog as a hobby. When clients came knocking to offer me paid writing opportunities, I was unsure.
Do I really know what I’m talking about? What if I write something that’s factually incorrect? How vulnerable should I be?
I figured that the risk was low, and now having written over 100 blog posts in the past two years, I can say confidently that my doubts were misplaced.
Of course, my self-doubt is not unique. “I have never considered myself expressive or eloquent, so I used to doubt that I would make a good technical writer,” frontend developer and writer Linda Ikechukwu told me. “However, the truth is that writing, like every other skill, can be learned and developed through practice.
Software engineer and writer Hrittik Roy defines technical writing as writing that is “all about communicating complex engineering topics in a way that is easy for the reader to understand, follow and execute without complicated language.” A technical writer’s job is to deliver technical information to another party clearly and efficiently.
Technical writing does not need to be flashy. Actually, it should rarely be flashy at all! “People who read technical documents are usually looking for answers,” Ikechukwu told me.“ It’s our jobs as technical writers to help them find those answers as quickly as possible, so they can get back to their own lives.” In order to do that, you need technical aptitude, clarity of thought, and knowledge of your reader base.
Essential Skills for Entry Level Technical Writers
Technical Aptitude: Writing About What You Know
When you first begin technical writing, focus on topics of which you have deep knowledge. “You need to know the intricacies of how things work internally and externally,” full stack developer and technical writer Ravgeet Dhillon told me.“ Only then you would be able to explain a topic to a complete beginner.
When you’re beginning, choosing familiar technical topics will allow you to focus on the craft of writing, instead of research. When I wrote about this topic for Stackoverflow, developer, consultant and author Adam Duvander advised that new writers should “pick a fun technical challenge you faced and share how you fixed it. If you do this every month or two, you’ll have more technical posts than almost any other working engineer.”
As you develop your technical writing skills, you can easily branch out into topics that require more research. “Pick a certain area of technology and start writing about it,” Dhillon suggested. “Only after that, learn the skills that are complementary to the main skill and start writing about them.” In this way, technical writing can be a method by which you improve as a developer. It acts as an in-road to on-the-job learning. The more you write, the more you will develop confidence in your communicative skills.
Clarity of Thought: Communicating Complex Ideas Simply
Technical writing focuses primarily on communicating information. You’re not trying to entertain or persuade readers of anything. You’re trying to deliver knowledge in the clearest, most coherent, and simplest way possible. “The flow of the article is very important in a technical piece,” Roy told me. “For example, you don’t want to jump steps or miss important details, making it hard for readers to follow.”
At the same time, remember that readers of technical writing are looking for answers. Ikechukwu suggests following the military acronym BLUF: bottom line up front. This means putting the most important information at beginning of each section and providing details afterward.
Technical writing is different from other genres in that, sometimes, the clearest way to express a concept is with the aid of a screenshot or diagram. Don’t hesitate to use illustrations when necessary. “Adding more illustrations to your writing is better than adding more paragraphs,” Roy told me.
Audience Knowledge: Matching Content to Readers
Your work should be useful to your reader, and those readers can vary. “Matching your article’s voice and technical depth to the intended readership will help you make the most impact,” Tyler Charbeoneau wrote on the Draft.dev blog. “While a manager might care about delivering business value, a developer might prioritize efficiency and ease of use.” Keeping your target reader in mind in the early stages of writing will help you structure your writing.
Consider where you might publish your work. If you’re writing technical documentation, your audience will likely be other technical workers in your field so you can write with a higher level of assumed knowledge. On a personal blog, you might want to reach a wider audience, so might want to write at a more widely accessible level.
How to Develop Your Technical Writing Skills
Writing is a practice, and like any practicable skill, the more you do it, the easier it gets.
Reading Technical Documentation and Taking Courses
Reading technical writing is one of the best ways to get a feel for the style. Write the Docs provides a thorough documentation guide, as well as many other resources to better understand technical documentation. If you write code, consider using the guide as a tool to document your own code.
Starting Your Technical Writing Blog
Beginning can be intimidating, and your work will never be perfect on the first draft. Choose a topic you understand deeply, or a problem you recently solved. Write about the topic, or narrate how you solved the problem. Once the words are on-page, it’s much easier to go through and revise your work to ensure it’s as clear, correct, and coherent. Bake time into your schedule for writing at least a few times a week. You’ll be amazed at what you can produce when you dedicate time to the practice.
Writing technical content for your personal blog is a great way to build a portfolio, which will help you land technical writing gigs. Blogging regularly shows clients you can reliably adhere to a schedule, while simultaneously providing examples of your work. As you write regularly, you’ll grow more comfortable with the format, and maybe even develop a readership that can turn into a client base. A consistent blog also acts as a “historical record,” as Head of Developer Relations at FusionAuth Dan Moore told me. If you write consistently about technical challenges that interest you, you may uncover new topics or angles that can lead to new opportunities. A personal blog shows potential employers you are engaged, curious, and creative—all great qualities for a technical thinker to have.
If you’d like to start your own blog, Medium, Dev.to, and Hashnode are all popular options for developers. For an even easier beginning, start with LinkedIn posts or Twitter threads to see what topics engage your audience. Then, expand on those topics.
Volunteering for Open Source Projects
Once you have built up work on a personal blog, consider reaching out to open-source projects or friends in your network. Ask to provide documentation or blog content for their projects. Though this work is unpaid, it’s an invaluable experience for learning about how to work with clients, and a great addition to your portfolio. Ikechukwu began writing on her blog, then for FreeCodeCamp. “Working with the editors at FreeCodeCamp helped me improve my writing and gave me the confidence to apply for my first paid writing gig,” she told me.
Finding Your First Paid Technical Writing Job
Pitching to Technical Publications
I started writing for my blog, and that led to a company reaching out to me to write for them. Small opportunities are a great way to test the waters and see if technical writing is a good fit for you. To find them, cast a wide net.
“I came across an article that listed about 7 technical websites that pay you for writing for them,” full-stack developer Raveet Dhillion told me. “I sent my portfolio to all 7 of them.” The more people see your portfolio, the more you have a chance that one will bite.
Look for freelance opportunities at places like Upwork and the Community Writing Programs list. Reach out per those opportunities and pitch yourself. The pitch process varies by publication and is best learned by doing. Some will have specific application processes, while others may simply want to see a portfolio or a few short pitches for potential articles you would write for them. Remember you’re selling yourself, so be confident in your skills and portfolio.
Cold outreach is also a viable strategy. If a company that interests you has technical writers on their roster, consider emailing cold and asking if they work with freelancers. Even if you are turned down, you’ve shown initiative and potentially made a new connection for future work.
For a new technical writer, rejection or lack of response can be intimidating or may cause self-doubt. But that’s how freelancing works. Be persistent!
Draft.dev is always keeping an eye out for new technical writers, so be sure to learn more and apply here.
Using LinkedIn to Find Technical Writing Opportunities
LinkedIn is an underutilized resource for new technical writers. “A random chat on LinkedIn with a German consultancy firm CEO helped me jump on the technical writing wagon,” Roy told me. He began technical writing, and as his career developed, he shared his articles on LinkedIn regularly. “Posting these posts on LinkedIn helped me get more clients, and the cycle continued.”
Sharing your blog posts, freelance work, or volunteer work on LinkedIn is an excellent way to let your network know you are doing this work consistently. As your work appears in regularly in the feed, you will be “top of mind” for your network if anyone is seeking out writers.
For Roy, a random LinkedIn chat started him on the path to technical writing. If someone in your LinkedIn network is doing something cool that interests you, consider interviewing them for a blog post or a volunteer post. Building relationships with clients you admire is often a gateway to future paid work.
Write the Docs Job Board for Full-Time Positions
If you find you love technical writing, consider pursuing it full-time. Write the Docs has a job board specifically for full-time technical writing careers.
Leveraging Your Professional Network
Your professional network is also a great tool to find new work. No one will consider you for writing opportunities if they don’t know you’re looking for them. Don’t be afraid to mention your writing endeavors to colleagues. Post about it online, and mention it in in-person conversations. You never know who might be looking for someone to fill your particular niche.
Starting Your Technical Writing Career
Developers and engineers have deep knowledge that companies need. Technical writing is a unique and in-demand skill engineers can develop to further their careers and find new opportunities. Learning a new skill like technical writing can be intimidating, but if you trust your technical aptitude, develop clarity of thought, keep your knowledge base in mind, and practice, you will find technical writing is a skill that can be developed like any other. With confidence in your skill, you can embark on capturing paid technical writing gigs successfully.
The range of technical writing services is increasingly vast. Today, there are thousands of potential categories to choose from, each with its own unique tilts, effects, and ROI. And whether you need a little or a lot, you’re bound to feel overwhelmed while hunting for the right option.
Even once you’ve narrowed down the type of technical writing service you want, you’ll still need to find a way to bring everything together. Not every team has an in-house expert (or an employee with specific technical writing skills), which is why picking an external partner is critical for bringing it all together.
If you’re in the technical writing market for any reason, you need to pick a service that has your needs in mind. Let’s take a gander through the different types of technical writing available, as well as some of the things you can expect from each type.
Technical Writing Options
It’s not enough to say that you need ‘technical writing.’ These days, it’s important to understand the phrase ‘technical writing’ for what it is: a massive umbrella term that encompasses dozens of varieties and variations of writing.
There are five major types of technical writing services to consider:
Documentation: From user manuals to walk-throughs, documentation includes any kind of technical writing that focuses on sensitive software information. It is often used to help new users become acquainted with a certain program, and address any questions or concerns with internal teams. Keep in mind that documentation is rarely if ever used for content marketing purposes.
Technical Marketing Content: The goal of this type of writing is to capture leads with actionable, valuable, and informational content. This may include comparison posts about different kinds of software, guides to blogging platforms, or even marketing tips and resources. The ultimate goal of technical marketing content is to position yourself as an industry expert, building trust and boosting sales in the process.
Landing Pages: If you’re trying to reach a technical audience with very specific lingo, regular copywriting just won’t cut it. Technical writing for landing pages provides detailed information that decision-makers may need to move forward with a sale. This includes specific acronyms, functions, or processes that speak directly to your audience’s needs.
Tutorials: Similar to technical marketing content, tutorials teach your readers how to accomplish a project, complete a task, or build an application. This provides a great deal of value to your target audience and creates lasting value both on and offline.
Blog Posts: Contrary to popular belief, blog posts are most certainly a type of technical writing. Depending on your field or vertical, you could use blog posts to disseminate technical content and thought leadership at scale (and for every specific audience). The more niche your blog content is, the better it will perform.
Your company may just need one of these technical writing services, or it may need two or three. In either case, it’s good to familiarize yourself with the purpose and function of each. Who knows: you might end up needing all of them someday!
Comparing 5 Technical Writing Services
Now that you’re more aware of the different types of technical writing, you can start the process of picking a provider that works alongside your needs. We didn’t rank these in any particular order, but we did start with what we feel has the greatest amount of technical expertise for growing startups and tech brands.
Draft.dev – Technical Marketing Content That Scales
Offering nothing but technical writing and content marketing, Draft.dev curates a wide variety of authentic technical writers from around the globe. All tutorials, blog posts, and marketing content are aimed directly at software developers, data engineers, and DevOps pros – all of which may be interested in partnering with your technical solutions.
With Draft, you’ll get ready-to-publish blog posts once a week depending on your plan. Only pay for content if you’re 100% satisfied, backed by our consistent quality and style that continuously impresses our technical clients.
We prefer to remain streamlined and specific in our work, extremely focused on our goal of delivering value-driven technical writing. While we currently don’t offer documentation, executive ghostwriting, or content strategy, we’d be more than happy to point you toward providers we feel are a good fit.
Most developers don’t want or aren’t interested in traditional marketing – something EveryDeveloper understands extremely well. This agency sources technical writers with a variety of backgrounds to create driven, knowledgeable, and opinion-driven content.
According to the website, EveryDeveloper currently offers writing for:
Blogs
Tutorials
Thought Leadership
Today, EveryDeveloper is mostly focused on technical strategy, landing pages, and content action plans. The writing provided is at a lower volume than other agencies like Draft.dev, and is best for smaller organizations. However, if you’re ready to start focusing on the strategic side of technical writing, this is absolutely a great place to start.
Owen Media – PR For Tech Companies
PR is a vastly underappreciated element of the average tech company. At Owen Media, the goal has been to hybridize PR with other elements of the marketing cycle to create a holistic approach. Press releases are used alongside analytics relations and media tours to bring credibility and brand authority to high-tech organizations.
Apart from their public relations services, Owen Media provides a selection of additional writing services:
Technical ghostwriting
Executive authorship
High-level or advanced technical writing
Owen Media leans heavily into the marketing side of technical writing. If you’re looking for more internal content or documentation, you may need to partner with a secondary agency.
Documentation – ZivTech
Documentation is a primary focus for ZivTech, a Philadelphia-based agency with an impressive roster of past clients. Apart from their design, development, and strategy services, ZivTech uses in-house writers to compose extremely detailed documentation work. They currently use HTML5 to create up-to-date guides alongside your team, ensuring that no one is left behind during the development process.
To date, the company offers documentation support that includes:
User guides
Product manuals
Release notes
Product installation guides
Walk-through demos
Again, bear in mind that ZivTech does not offer any technical marketing writing (although documentation can be used for such a purpose). Their service is best for assisting internal or external teams with detailed walk-throughs of software usage – which is critical to just about every technical industry.
Jono Bacon – Technical Communities
Last on the list (but most certainly not least), Jono Bacon provides high-quality writing services to industries in technical communities. And when we say ‘communities,’ we mean actual online communities. Forums, dev blogs, and other types of online communities are the sole focus of Bacon’s expertise.
Jono offers services that include:
Community Management
Developer Workflow and Relations
Innersource and Internal Community Management
Public Speaking Engagements
Keep in mind that Jono Bacon doesn’t offer any tech marketing, nor does he specialize in other types of technical writing services. But if you’re looking for an outstanding resource with an enormous amount of experience building technical communities, this may be the perfect option for you.
Choosing The Right Kind Of Technical Writing
In the content industry, knowing what you want and need is key to a successful outcome. As you start narrowing down what you’re looking for, you’ll want to weigh the potential pros and cons of each writing service.
Ask yourself:
Will you need additional technical writing services in the future? If so, you may not want to choose just one platform with a singular focus. You’ll save more money in the long run (and have fewer headaches) if you choose a service that scales alongside you.
How much are you willing to spend on your technical writing services? Some platforms list prices right from the get-go, while others have specific or customizable quotes.
What’s the scale or timeline of the technical writing you need? If you choose a smaller service, it may take several months to get where you want to be. Small agencies may produce a limited amount of content per cycle, which reduces how fast branded content can reach the market.
There’s a lot of thought that goes into a technical writing partnership, no matter what type of content your business is looking to secure. As you narrow down your potential list of providers, be sure and take all the time you need to ask questions, evaluate options, and choose the best possible path forward.
If Draft.dev is right for your technical writing needs, just give us a call! We’re always jazzed to chat about tech writing – and we’d love to learn more about how we can help. Talk soon!
TL;DR: Technical writing is a critical skill for engineers that improves understanding, enhances developer experience, and opens career opportunities. Key strategies include:
Read quality content regularly to internalize good writing patterns
Create detailed outlines before writing to structure your thoughts
Keep language simple and direct to ensure clarity across diverse audiences
Use writing assistants like Grammarly to catch errors and improve quality
Write consistently starting with small, manageable topics you know well
Engineers who master technical writing gain deeper technical understanding, improve team communication, and unlock new career paths in developer relations, management, or professional technical writing.
If you are an engineer hoping to improve your technical writing, you’re not alone. Writing is one of the most important “soft” skills you can have. Honing that skill will help you develop a greater understanding of technology, improve developer experience for whatever product you work on, and possibly advance (or change) your career.
Technical writing helps solidify your understanding of a topic. One of the best ways to internalize knowledge is to explain it to others. It forces you to think about why things are done a certain way and address all of the steps necessary to make something work. Once you’ve explained a topic in writing, you will be more confident about your understanding of that topic.
Why Technical Writing Matters for Software Engineers
Are you creating a product or working on one? Having great written information about your product helps to improve the developer experience (DX). Accessible documentation, easy-to-follow tutorials, and even descriptive variable names can be the difference between a tool that’s a joy to use and one that makes developers want to throw their laptops across the room. This is why every team should include at least one great technical writer.
If you are that great technical writer, your skill can help you in your career. Being an accomplished developer is impressive, but if you can code and write, that’s extra special. Writing well is crucial if you ever want to move into management, because you will need to be able to translate code for people in non-technical departments.
If you don’t want to go the management route, writing can open up other exciting career paths, like developer relations or technical writing for companies like Draft.dev, which matches tech professionals to their ideal writing assignments.
But even if your career aspiration is simply to be an excellent engineer, writing is important. You are likely communicating every day in writing, whether it be via GitHub pull request, API documentation, or Slack messages to your colleagues. This is even more relevant if you work remotely. Communicating effectively in writing is a crucial skill.
What Makes Technical Writing Difficult?
Some people have the mistaken idea that writing is easy. Everyone writes, after all—on Twitter and Facebook, or in emails and texts. But writing well is an acquired skill, and, like coding, requires practice to get right.
For engineers in particular, it can be difficult to “step back” into a less knowledgeable perspective. Depending on your audience, it is likely that you will need to explain things that seem obvious to you. You may forget to mention steps you do without thinking, like installing dependencies using npm or navigating into the correct folder before starting a server. Skipping steps can spell frustration for your readers, so it is essential to consider this when writing. Technical writing, especially for beginners, often requires you to reset your knowledge of a topic to zero, which is not always an easy task.
Similarly, you may have difficulty understanding your target audience. Are you writing for new developers, senior engineers, or business users who have little to no knowledge of code? What are your readers hoping to take away from your article or tutorial? You must be able to answer these questions before you start writing and keep the answers in mind as you write.
Jargon and acronyms that may be appropriate for one audience will leave another one confused. On the other hand, spending a paragraph explaining what a function is to a senior engineer will ensure they don’t read the rest of your article. And it’s not just about technical know-how. You need to internalize what your audience is looking for when they read your article, then make sure you follow through on giving that to them.
Finally, you may struggle with choosing the right words and structure of your content. In a piece of technical writing, every word you write must be accurate, and every sentence must be correctly placed. You may find yourself agonizing over whether to call something a “function” or a “method” or whether a process should be written in a paragraph or bullet points. Technical writing requires an eagle eye to spot confusing structure or inaccurate wording. You need to take the same care with your writing as you do with your code. It’s just as important.
5 Proven Strategies to Improve Your Technical Writing
It’s true that writing technical content is difficult, but you can take some concrete steps to improve your skills. Here are some tips that will help you in your technical writing journey.
Read High-Quality Content Regularly
If you are a software engineer, you are most likely familiar with the concept of “GIGO,” or “Garbage in, garbage out.” This concept applies to writing as well as to computer science. What you put in as a reader influences what you produce as a writer. When you read well-written content, it helps you internalize a good narrative voice. So if all you read these days is tweets, try to switch it up and grab a book.
It doesn’t need to be a book about writing or computers. Read for pleasure! Pick up a novel, a collection of short stories, or some narrative nonfiction. You will find that the more quality writing you read, the more your own writing will improve.
Create Detailed Outlines Before Writing
When coding, it is always a good idea to write pseudocode before doubling back and building your solution using an actual programming language. Similarly, an outline can help tremendously with technical writing.
Writing an article is an iterative process. You must keep coming back and fleshing out your article more and more with each pass-through. The original outline should be basic and cover the general gist of your article. Go through each point of the outline and expand on it with a few bullet points, making sure to include all necessary steps if you are writing a tutorial. Then expand your bullet points into sentences and paragraphs. Each time you circle back, your work will look less like an outline and more like an article.
This method is often helpful when you are feeling writer’s block. If, on one pass-through, you aren’t sure what to put in a section, write yourself a note about what will go there and move on. You can go back later and address your notes.
Keep Your Language Simple and Direct
Even when you are writing for advanced readers, it is important to be clear, concise, and direct in your language. Avoid regional slang, unnecessarily big words, and overly complicated sentences. English may be tech’s “universal” language, but remember that your readers are likely to have different cultural and linguistic backgrounds. They will have varying levels of English proficiency, so don’t make it difficult for them.
Use standard English and stick to the topic. Don’t pause your tutorial to tell a joke or craft a complicated metaphor. Just explain your topic clearly. Using a style guide, such as The Chicago Manual of Style, will help you maintain consistency in everything from sentence structure to general formatting.
Another way to ensure clarity is to know when a well-placed GIF, screenshot, or code sample is superior to a written explanation. If you are struggling to come up with the words to describe something, stop and consider if supplementing with a visual example would make it easier for you to explain and for your readers to understand.
Use a Writing Assistant Tools
Tools like Grammarly are extremely useful for catching errors and improving your writing. They can find problems like misplaced or missing commas, run-on sentences, and repeated words. They can also give suggestions on how to make your articles clear, correct, and engaging.
Use common sense when running these tools, however. They are far from perfect, and you need to know when to take their advice and when not to. It is especially important to be vigilant when writing highly technical pieces, because tools like Grammarly aren’t designed to check for technical accuracy. They will sometimes suggest incorrect words or offer synonyms for terms that can’t be reworded. So before you accept that synonym for “function,” take a moment and remember that while useful, automatic writing assistants are still not as smart as you are.
Build a Consistent Writing Habit
Establishing a new habit can be intimidating, but don’t let yourself get overwhelmed. You don’t need to start out by writing a ten-part blog series or a 300-page ebook. Start small. Pick a topic you know well and write about it in small bites. Are you an expert on React? Write a tutorial on how to use the useEffect hook. Do you live on the command line? Write a rundown of common terminal commands. Make a blog on Hashnode or Medium and create some content.
Do a little bit of writing every day. It doesn’t need to be a full article—just get some sentences down. In time, writing will become such a regular part of your routine that your day won’t feel complete without it.
Conclusion
In this article, you have learned some techniques for improving your technical writing skills. If this has inspired you and you would like to get paid while you write, consider becoming a technical writer for Draft.dev.
Draft.dev matches technically proficient developers to a huge variety of writing tasks. It’s an incredible opportunity to share and expand your expertise about technologies that interest you while making money doing so. For more information and to apply, head over to our signup page.
TL;DR: Remote technical writing combines technical expertise with clear communication skills to create developer documentation, tutorials, and guides. Success requires understanding diverse audiences, maintaining strong organization, staying current with tech trends, and building a diverse portfolio. Working with agencies like Draft.dev provides steady work, supportive teams, and flexibility. Key skills include audience adaptation, efficient content structure, and willingness to tackle new technical topics.
I’m the first to admit that my path to technical writing was somewhat unconventional. My degree was in International Studies, and after flirting with a career in politics (let’s not discuss how that went), it became clear that a change was needed.
Thankfully, my studies had armed me with extensive writing experience and I also had a deep fascination with software, hardware, and all things tech. Over four years later, with ample technical articles under my belt, I now humbly introduce myself as a technical writer. As I often like to joke, I’ve truly become a professional nerd and I wouldn’t have it any other way!
I’ve had a blast writing for clients in the spaces of software as a service (SaaS), platform as a service (PaaS), and infrastructure as a service (IaaS). One-off gigs have transformed into long-term relationships, audiences have grown more diverse, and my written content has traversed the spectrum of technical depth. These experiences ultimately led me to Draft.dev, where many of my content requests now stem from.
Draft.dev is a technical marketing content agency for startups. The organization is made up of a knowledgeable group of writers, editors, and leaders that oversee writing projects from start to finish. The awesome folks at Draft.dev create personalized, monthly content plans for tech companies, in this way building strong business relationships, too.
While I enjoy my work as a technical writer, I’ve definitely experienced my fair share of challenges. In this article, I’ll share my experience, as well as some tips to help you improve and succeed in your technical writing.
What Makes Technical Writing Different from Other Writing Styles?
Technical writing has a reputation for being a little dry (compared to copywriting, for example), and that can certainly be true at times. Technical articles typically focus on the facts and present them in a regimented manner.
You could be writing a step-by-step software guide, a platform comparison, or breaking down and explaining a piece of tech. Instead of moving your readers emotionally, your goal is to communicate complex information clearly and succinctly. This usually leaves less room for “color” or personality, though it isn’t always the case (more on that soon).
What can help immensely in this regard is having a thorough understanding and enjoyment of the topics you’ll be writing about. Ideally, the subject matter will be exciting and motivate you to continue from one sentence to the next.
It’s also true that you might not be in the mood to produce content on certain days. However, tackling topics that spark joy can help you write more sharply and maintain productivity. That’s even more important in a remote role, where you’re expected to be self-motivated.
Understanding Your Technical Audience
Technical writing exposes you to all kinds of readers. You might be catering to developers, IT administrators, CTOs, and even non-technical folks in some cases. This is especially true when working with content agencies like Draft.dev. Different companies will have different content goals and the content you write will therefore target diverse groups of specific interests—they might be in the trenches coding or making decisions at the helm.
Writing for Developers vs. Decision Makers
Matching your article’s voice and technical depth to the intended readership will help you make the most impact. While a manager might care about delivering business value, a developer might prioritize efficiency and ease of use. Reader personas can therefore diverge, and your writing needs to address the target audience each time.
Accommodating Different Knowledge Levels
Even when writing for specific audiences though, you should keep in mind that readers might possess varying degrees of technical knowledge. You can’t presuppose their level of familiarity with the topic, for example when it comes to acronyms or even additional sources of information. Best practice dictates that, for the former, you should spell things out the first time they’re presented, while for the latter, you should point readers to supplemental documentation or other pages, as doing so can help boost their engagement.
When it comes to writing for more general audiences, you’ll often be tasked with striking a balance between making information both approachable and educational; you have to be aware of when you need to simplify your language, and where digging deeper into the nitty gritty is appreciated. You don’t want to alienate your readers but you also don’t want to bore them.
Overcoming Remote Communication Challenges
Working remotely can present a challenge. You might not have immediate access to clients, engineers, or teammates, and learning about your audience and objectives might take additional time as you communicate more passively via email or a messaging platform.
As a rule, it’s always worth requesting a target audience brief with each assignment. It’s also helpful to have the company’s style guide handy, if they have one. Don’t be afraid to ask questions and request more resources.
Essential Organization Strategies for Technical Content
I mentioned that technical articles should be regimented, but what exactly does that mean? Consider a user guide, for example, where you’re explaining how to configure and deploy Kubernetes. While experienced developers may be skimming the guide to double-check they’ve got the process right, less experienced readers will need you to direct them in a step-by-step manner. The two types of readers will be reading the article in different ways, and it’s important to accommodate both styles of consumption.
Structuring Content for Multiple Reading Styles
Technical readers approach content differently based on experience level. Experienced developers skim for specific details while beginners need step-by-step guidance. Accommodate both by:
Eliminating unnecessary wordiness
Including clickable table of contents for longer pieces
Using descriptive headers that aid scanning
Creating logical content hierarchy
Technical readers usually don’t appreciate when writers beat around the bush through excessive wordiness or irrelevance to the key topic of the article. Try your best to remove the fluff and structure articles in logical ways. Be respectful of your readers’ time; they’ll love you for it.
Enhancing Readability with Visual Elements
Similarly, adding media like images and videos can boost the readability of your text: code blocks, diagrams, and header images can provide context to sections. Meanwhile, GitHub repositories and other resources are not only important for a good reading experience, they are also critical when you’re trying to move readers through multiple technical articles, or direct them to documentation. A good technical writer will offer readers multiple pathways through which they can bolster their knowledge on a given topic. It’s generally good to avoid “dead ends.”
Staying Current in the Tech Industry
Writing articles regularly is a surefire way to hone your skills, but building knowledge of your industry is another way to remain sharp. You’ll be able to understand emerging topics more readily and be more able to formulate article pitches, if that’s part of your responsibilities. It can also help you uncover valuable, citable sources of information.
Similarly, it might be helpful to follow tech industry experts on LinkedIn, Medium, and other platforms. These authoritative voices can offer a wealth of knowledge: they can point you to resources or even make themselves available for conversations if you ask politely.
Part of what makes the industry so strong is its sense of community. You can capitalize on this and even use that buzz as inspiration to keep going.
Growing Your Technical Writing Career
It’s hard to grow as a remote writer if you aren’t willing to tackle new topics. In other words, sticking squarely to a niche keeps you one-dimensional as a writer. It’s also an express route to burnout.
Expanding Beyond Your Niche
Limiting yourself to familiar topics creates career stagnation and burnout risk. Tackling diverse technical subjects:
Demonstrates adaptability to potential clients
Develops versatility and marketability
Prevents monotony from repetitive content
Builds comprehensive portfolio strength
One of my strongest selling points has been my portfolio. While I can talk all day about topics I’m willing to work on, there’s nothing like demonstrating that aptitude directly.
Building Your Technical Writing Portfolio
Maintain organized records of your published work (respecting contract terms). Options include:
Personal portfolio website
Shared Google Drive folder
Professional profiles on writing platforms
GitHub repository for code samples
Your portfolio demonstrates capabilities more effectively than descriptions alone.
Diversifying Content Types
Expand skills by creating various content formats:
User guides and documentation
White papers and industry reports
Release notes and changelogs
API documentation
Tutorial series
Each format develops different aspects of technical writing expertise.
Finding Remote Technical Writing Opportunities
Seek open roles and don’t be afraid to apply. Short-term projects are great, as are long-term arrangements. Choose what works best for you. Keep in mind, however, that forging long-standing partnerships with a number of clients is a great way to prove that you’re dependable. It also offers greater financial stability, which isn’t anything to sneeze at in the freelancing realm.
Pro tip: When applying, make sure to include a cover letter for a technical writer position so you can showcase your capabilities and show how you can be a good fit.
My Journey as a Remote Technical Writer at Draft.dev
I’m thrilled to say that my time as a technical writer has been incredibly positive. It’s also been quite the journey. My exposure to different topics has grown exponentially over time, and I’ve had the opportunity to work with some amazing people the world over. I’ve harnessed many digital communications channels and productivity tools, and operated within different content production processes.
I’ve absolutely faced challenges. I’ve taken on new topics and struggled to come up with words. Making errors along the way—both grammatical and technical—has ironically been essential to improving. I always try to treat each project as a learning experience. Learning how to take constructive criticism in stride, and navigating the infamous writer–editor relationship (don’t worry, they don’t bite) have been critical.
My experience with Draft.dev in particular has been great. Everyone I’ve worked with has been incredibly responsive, helpful, and understanding when unforeseen circumstances have interfered with projects. The writing process has been clear and consistent. As with many clients, I’ll receive a brief with every assignment that describes the audience and the client while providing a short synopsis. Detailed outlines are always provided (so I’m not starting from scratch), as are linked resources for citations.
Communication is quick when you have to bounce ideas or questions off the team and the editing process isn’t overbearing. The team is quick to offer technical information and genuine assistance through revisions. It’s also easy to fit assignments within my own schedule. This hasn’t always been my experience, so it’s a refreshing change of pace. I’d absolutely recommend Draft.dev as a place to get one’s agency feet wet.
Working with Draft.dev’s Content Agency Model
Draft.dev provides structured support for remote technical writers. Each assignment includes:
Detailed audience briefs
Client background information
Comprehensive outlines
Linked citation resources
Responsive team communication
The editing process focuses on improvement rather than criticism, with technical assistance readily available. Schedule flexibility accommodates personal availability while maintaining consistent quality standards.
Key Takeaways for Aspiring Technical Writers
As you can see, becoming a remote technical writer requires a strategic approach. You should be mindful of your audience, your clients, and your own level of comfort when tackling new assignments. Write with care and mindfulness towards your reader. Technical writing takes plenty of time to become skillful at. Being patient and open-minded will work wonders for your career.
Are you looking for reliable and exciting work? I strongly encourage you to give the folks at Draft.dev a shout. There’s no shortage of opportunities, and you can work at your own pace, and according to your availability. The team is fantastic to work with and excels at remote collaboration. The writing process is simple, and you’ll feel supported every step of the way.
Ever thought of turning your professional expertise toward writing? Or perhaps you’ve realized that your company needs a skilled writer who understands the ins and outs of your trade. In either case, it’s time to consider technical writing.
What Is Technical Writing?
Technical writing is the concept of writing about the technical knowledge of an industry—think of content like tutorials and documentation. This is writing that educates readers in the technicalities of a certain discipline or task, often aimed at audiences who have at least some area knowledge themselves.
Technical writing is often B2B or B2C content that is tightly focused on education. How does this tool connect with that tool? Which language is better for this use case? Should a software company rehaul its processes to match the trendy new workflow everyone’s talking about or is the ROI not worth it? It’s less about selling the reader on a product and more about educating them in practically achieving a goal.
This article will focus on technical writing for software engineering specifically, but just about every industry has a need for technical writers to clearly explain its hows and whys.
If You’d Like to Try Technical Writing…
If you’ve been in your industry for a while, you may already have some technical writing pieces to your name without even realizing it. Did you help write documentation for a product you built? Did you add to the blog of a startup you worked for a couple years ago? Gather those links and skip to the next section.
For those who need to start at the beginning when it comes to technical writing, you might want to begin with your own blog, either on your own website or a platform like Medium, jot down some ideas for a couple short blog posts. What could you write 1,000 words about that would be helpful for other software engineers to know more about? What troubleshooting did you recently accomplish that had you piecing together tips from five different forums? Get your thoughts organized, don’t forget to proofread your writing, and get it online.
The only way to be a good writer is to write, so focus on consistency and quantity more than perfection, especially if you’re writing for yourself.
And You’d Like to Get Paid For It
Ready to offer your technical writing services for hire? The good news is that these days, most technical writing opportunities are remote. Consider where you like to get your own industry news online; what are the sites you check first when you need answers? Have you run into a blog or a writer that you particularly trust?
Follow the rabbit trail of links that fan out from your usual haunts, and you’ll see where others are writing for your field. If a writing opportunity looks interesting, learn how the company wants writers to apply. They’ll probably ask for links to any published technical writing you may already have. Definitely have a technical writing cover letter ready to go.
First, Understand What You’re Being Asked to Write
Each content agency, news site, online magazine, and company blog will have its own expectations when it comes to technical writing, so be sure you’re comfortable with what they’re asking you to provide. After all, there’s a difference between writing a tutorial, comparing two or three tools, and composing a roundup of the top twenty JavaScript plug-ins of the year.
Then Be Prepared for Style Guides and Edits
Online publishing is only getting more sophisticated as individual businesses become more comfortable producing their own content. Don’t be surprised if you’re asked to adhere to a style guide or if your work goes through some edits.
Most companies with an established marketing department will have their own style guide, but you can get an idea of what you might be asked for in any of these style examples, including from Draft.dev.
The more closely your work sticks to the required style, the less rigorous the edits will be on your writing. Still, you should expect at least one round of edits from whoever you’re writing for. Draft.dev has between three and five rounds of edits per article, encompassing a technical review, a development edit, and a copy edit.
If You Need a Technical Writer…
Technical writing is no joke. It takes attention to detail, a willingness to research, a skilled hand at writing, and the ability to take an edit professionally. Many companies see the need for technical writing but either aren’t large enough to staff their own content creation or would prefer to focus on their core skills and leave the writing to someone else entirely.
And You’d Like to Find a Good One
If your business is looking to establish an ongoing relationship with a freelance technical writer, we’re happy to share our hiring tricks at Draft.dev. Finding the perfect writer for you is a multi-step process—from knowing exactly what you’re looking for to knowing where to look and how to reach out to them—but in the end, you’ll be happy you put in the time and care in your search.
First, Consider What You Need From the Writer
Ideally, you’re looking for someone already experienced in technical writing. They’ve either written consistently on their own bit of internet real estate, or they have at least a few bylines with voices of authority in the industry. Other than that, what you’re looking for in a writer is not necessarily the same as what your competitor might want. Your marketing goals, your client demographic, and the messages you want to convey all make for your own unique wish list.
However, there are some red flags that will probably always warrant a polite no, thank you email from your hiring manager.
Someone who’s written across a wide variety of unrelated industries is probably an experienced content marketer who’s great at research. Chances are you need someone with deeper knowledge. Software engineering in particular doesn’t lend itself to turning quick research into authoritative writing. Other flags to be watchful for include a generally unprofessional attitude (you need this person to be self-motivated and reliable), a lack of familiarity with common online collaboration tools (Google Suite, GitHub), and field experience but too little of it (you don’t want to hand an advanced Kubernetes assignment to someone who finished a code boot camp last week).
Then, Consider What You Need For Your Team
As already mentioned, finding the correct technical writer for your goals takes time. Editing their work and getting it ready for publication on your platform are other time sinks. If your team is better suited to focusing on your core business rather than creating content resources for your audience, consider working with a technical writing service instead.
These services come in a variety of shapes and sizes, so again, take time to get clear about what your own business needs from one of them. Are you looking for a full-service marketing agency, or do you want them to prioritize industry knowledge while you handle the content publication and promotion? Do you want to be one of a few clients for a boutique content agency, or are you looking for something less infinitely customizable and more of a low-code/no-code solution?
Want to learn more before getting in touch with us? Take a stroll through Draft.dev’s blog. You’ll find a variety of information ready to help you determine where you’d like to go next with technical writing.
TL;DR: Persuasive technical content combines clear reasoning with authoritative expertise to influence software engineers and technical decision-makers. Unlike basic technical documentation or marketing content, it requires deep subject matter knowledge and subtle persuasion techniques.
Key success factors for technical persuasion:
Authority building: Combine research, expert quotes, and personal experience
Clarity first: Perfect grammar and logical flow are non-negotiable
Subtle approach: Guide readers to conclusions rather than forcing them
Personal connection: Real experience resonates more than theoretical knowledge
Both-sides approach: Address counterarguments to build credibility
Success requires establishing expertise, asking thought-provoking questions, and providing value before attempting persuasion across formats like technical blog posts, conference talks, and engineering leadership content.
I’ve gotten to be a big fan of David Perell’s writing. He writes long-form, persuasive content where he dives really deep into a topic and then explains its relevance in philosophy, business, or both.
While not technical, these pieces are interesting, inspiring, and (as I’ll focus on today) persuasive. They each leave you with an impression that something is wrong with the world or its traditional ways of thinking and give you a roadmap to break out of it. While you may not agree with all of Perell’s conclusions, most of his arguments are well thought out and clearly presented.
Persuading software engineers or engineering leaders is essentially no different from persuading writers and businesspeople, but writing persuasive technical content is really hard. Persuasive writing is among the most difficult types of writing to do, and writing technical content requires a very specific background and level of experience.
But, persuasive technical writing is incredibly valuable because it’s so rare. CTOs and technical visionaries who do it well often make the front page of Hacker News, and will find it easier to recruit, sell, and inspire others toward their goals.
In this piece, I’ll introduce some of the things that make persuasive technical content so hard. I’ll share examples of writers I’ve seen who do it well, and I’ll offer a few tips as an observer and writer. While you can’t get really good at writing without practice, I hope having some direction will help guide you towards becoming a better persuasive writer.
What is Persuasive Technical Content?
Before I jump into the how, let’s talk about what persuasive writing is and why people do it. Persuasive technical writing is a form of technical thought leadership where the author is attempting to persuade their reader to agree with them on some topic. Typically, the author wants the audience to see the same problem or solution they do.
For example, in 2018, I wrote a blog post titled, “The Bulk of Software Engineering is Just Plumbing,” in which I made the case that most of the work software engineers do is simply connecting pieces of software that other people built for them.
Just as a good small business owner should hire a humble plumber who knows the standard tools, and pay them market rate, a good engineering manager should hire humble team players who use industry-standard tools to build reliable software, and pay them market rate.
I wanted engineers and hiring managers to adopt a bit more humility in the profession, and based on the reception I got on Reddit and Hacker News, many readers agreed.
While I would never claim to be a master of persuasive technical writing, I’ve tried (and failed) enough times to tell what works. In 2020, I wrote almost 100 essays and blog posts, many of which were persuasive technical pieces. So, let’s take a look at some of the attributes that good persuasive writing exhibits and how you can use each in your practice.
In Order to Persuade, You Must be Understood
Good writing is fundamentally good thinking that follows a logical path and is easy for someone to follow. – Jeff Bradford, President & CEO of the Bradford Group
As with any effective form of writing, your work must be well-written and organized. Some forms of writing are more forgiving (for example, tutorials), but with persuasive writing, the bar is especially high. Poor grammar and hard-to-follow lines of reasoning will turn readers off quickly.
Persuasive Technical Writing Should be Authoritative
A statement is persuasive and credible either because it is directly self-evident or because it appears to be proved from other statements that are so. – Aristotle
If you’re trying to reach a knowledgeable audience with a persuasive argument, you need to be perceived as knowledgeable about the topic. This is called “building authority,” and there are many ways to add it to your writing:
Research
Quotes
Personal Experience
One of our Draft.dev writers, Keanan Koppenhaver, does a good job of this in his persuasive writing. This piece he did for Fabric.inc compares Shopify and Salesforce Commerce Cloud by going through specific features and limitations of each platform.
He draws on his personal experience in software as well as publicly available documentation and forum posts to bolster his arguments. Being a CTO and consultant helps boost his credibility as well because a piece like this written by a Fabric marketing executive wouldn’t be nearly as convincing.
Persuasion Should be Subtle
Written arguments often fail when they employ ranting rather than reasoning. – Tara Horkoff, Writing for Success
The best persuasive writing doesn’t beat you over the head with the author’s conclusion. Instead, it guides readers toward the desired conclusion by:
Establishing authority
Asking questions
Being helpful
Showing both sides of the argument
Some persuasive writing doesn’t even tell readers what to think, but instead, just leaves readers with an open question. I recently ran across a Twitter thread by Sam Altman predicting the end of the college education system in the US:
I think US college education is nearer to collapsing than it appears.
While he presents some partial answers, it’s more focused on the problem and implied question (“what comes next?”) than the solution.
Persuasion is Often Personal
I have a theory that the best ads come from personal experience. Some of the good ones I have done have really come out of the real experience of my life, and somehow this has come over as true and valid and persuasive. – David Ogilvy
Finally, some of the best persuasive writing is borne from personal experience.
For example, a couple of years ago, I noticed that asking experts for direct advice was almost never helpful. Instead, I started asking them how they solved a particular problem or managed a certain conflict.
I started with a topic that I had personal experience with but layered in data, quotes, and supporting arguments from others who had spent even more time with the topic. While the piece never got a ton of attention online, I refer people to it when they ask me for advice, so I’ve found it useful in other ways.
Conclusion
While we do a little bit of “light” persuasive writing at Draft.dev, I encourage most companies to do this form of writing in-house. If you’re a startup, your founders are probably the best people to make a compelling case for your world-view, and if you’re in a large enterprise, you probably want your PR or executive team collaborating on these pieces.
On the other hand, if you’re a software developer or engineering leader who just wants to write persuasive technical pieces, I’d encourage you to do so on your own blog. While some companies may pay you for these, you’ll get a much more authentic reception when you do it for your own gratification.
Hi! My name is Yulia, and I have been working as a technical writer for the past three years. Last year, I started to write for Draft.dev, a technical marketing content agency for software startups. Draft.dev works with quite a few companies with different tech stacks and is constantly looking for talented new writers. I’ve always been interested in technology and writing, and this position helps me learn new things and improve, as well as share what I’ve learned with others.
Writing is a great way for technical specialists to get recognized in the community, share their expertise with potential employers, and improve their communication skills, especially if English isn’t their first language. In this article, I will share some tips for creating technical writer cover letters so that you can successfully kick off your writing career.
About Technical Writer Cover Letters
From my experience, being able to write a good cover letter is extremely important if you want to land a job in writing. In technical writing, formal education and other qualifications don’t matter. However, you need to know how to “sell yourself” and provide the hiring manager with the relevant information they need, such as your technical background, your writing experience, and which technologies you can write about.
Don’t just copy cover letters from the internet. Make sure that yours is unique—believe me, content editors and managers receive dozens of cover letters daily, and they’ve seen them all. Write your own authentic email in a friendly, informal fashion, and don’t be shy about showcasing your best attributes.
Developers with no technical writing experience often aren’t sure how to convince the editor that they’re a good fit. In this case, explain why you’re interested in the position and what knowledge you can bring to the table (for instance, ten years of experience in programming or experience dealing with the product and the client side). If you have more general experience with writing, you can link your social media, academic papers, or other materials that show your command of the language.
However, the best thing would be to write at least one post on Medium about a technical topic that interests you. This way, the agency can evaluate your expertise, language, and logic.
How to Write Technical Writer Cover Letters
Following are some suggested steps to follow in writing your cover letter for a technical writing position:
What Your Letter Should Say
Your cover letter should contain all the necessary information about you that helps the employer make a decision. First, introduce yourself and explain why you’re writing:
Ex:
Hi!
My name is Dan, and I’m an Android mobile developer. I understand that you’re looking for technical writers, and I would like to apply.
Make sure that your email is structured and well-formatted. When I write cover letters, I usually structure them like this:
1. Relevant education: This includes degrees and online and offline courses. You’re not required to have a degree in computer science or engineering, but if you do, it’s worth mentioning, especially if it’s a master’s or a Ph.D. Not only is this a plus for you, but it will also help the company to offer you writing assignments that suit your expertise.
Ex:
I have a bachelor’s degree in computer science from Cornell University. I’ve also acquired Google Android Developer Certification and IBM Certification.
2. Relevant work experience: This means both in tech and in writing. Talk about your programming experience and technical writing experience separately since both are important components for this job.
Ex:
I have four-plus years of experience in software development. Right now, I’m working at Amazing Software Company as a middle software engineer. My team creates mobile applications for Android. Some of the projects that I’ve worked on are CoolApp1 and CoolApp2. As part of a promotion for these projects, I’ve written several blog posts that were published on HackerNoon and got a lot of positive comments. I really enjoyed writing them and would like to continue sharing my knowledge with a wider audience.
3. What you’d like to write about: Tech is big, and nobody can write about everything. Mention what programming languages, frameworks, or technologies you know best and have experience with. If you’re learning something new, include that as well.
Ex:
I’m most interested in writing about Android development, UX/UI design, and project management. The programming languages that I write in are Java, Kotlin, and JavaScript. I have plenty of experience with Android Toolkit and crash analytics apps.
4. Writing samples: Writing samples are the most important factor in whether you get hired. If you’ve written posts for your own or your company’s blog, include them. If you don’t have any samples, you can create a post for your blog or post something on Medium. Not only is this helpful for employers, but it helps you find out whether you enjoy writing. You can also include links to your GitHub repositories to showcase the quality of your code.
Ex:
Here are some examples of my work:
Let me know if this looks like a good fit for you.
Best wishes,
Dan
Don’t make a cover letter too long. I try to keep them to about ten sentences maximum. Let your work speak for itself.
What Your Letter Shouldn’t Say
Your cover letter should be straight to the point, so don’t include irrelevant information. For example, if you don’t have any blog posts to show, don’t mention that you have always liked writing and even wrote a couple of stories as a child. This isn’t relevant experience, and it doesn’t sound professional.
Another common mistake is to leave out the cover letter and send your resume by itself. A cover letter shows your interest in the job as well as your respect for the person who will open your email. Instead of making the editor comb through your ten-page CV trying to understand what you can do for them, give them exactly what they need. It will be appreciated.
What to Know about the Company
Writing cover letters starts with reading. Do your homework and investigate what the company does, who their clients are, and what niches they work in. If you’re a Haskell developer, it’s highly unlikely that you’ll land a job writing for mobile developers. It’s also a good idea to demonstrate in your cover letter that you have studied what the company does and you’re interested in it. Link your relevant experience or knowledge to the company’s mission, and you’re much more likely to be hired.
Less Experience vs. More Experience
For technical writing, the demand is generally higher than the supply. This means you don’t necessarily need to be a senior developer or a writer with ten years of experience to become a technical writer. If you’re a junior developer, it’s okay to say that. Different clients with different audiences need different types of content: from high-level posts to deeply technical long-read guides with code snippets.
Example of a Successful Cover Letter
As an example, below is the cover letter that landed me a technical writing job at Draft.dev:
Hi, Chris!
My name is Yulia, I’m twenty-five, and I have been writing about tech for three years now.
I started as a junior software developer at [company name], where I worked on projects in the domain of machine learning and data science. Right now, I work at [company name] as a middle software developer. I mostly write in Python and JS and work with TensorFlow, Microsoft Azure, and AWS.
I am interested in working with you because I would like to share my experience with wider audiences, grow as a writer, and help great startups and companies gain more recognition.
I’m a quick learner and passionate about language and technology, especially artificial intelligence.
Link to my blog:
Twitter:
Hope to speak to you soon!
Have a great start to the year,
Julia
Conclusion
Writing a cover letter for a technical writer position is a necessary step since it allows you to show yourself in the best light and introduce the reader to how you can be useful for them. This might seem like a tricky task, but in reality, it’s simple if you follow these rules:
Keep it short and friendly.
Showcase your relevant experience, education, and skills for the position.
Provide links to your portfolio.
Write the letter in your own words.
Draft.dev is one of the best places for technical writers from different fields to share what they know and get paid for their words. It offers clear guidelines on its editing process, a convenient writer portal where you can select tasks based on your interests, and great pay rates. If you’ve been thinking about becoming a technical writer, give it a try now!
TL;DR: Technical comparison articles evaluate multiple products or technologies to help readers make informed decisions while establishing your expertise in the field. Unlike roundups that list features, comparisons provide detailed analysis of why specific tools work better for different use cases.
Key elements of effective technical comparisons:
Audience awareness: Tailor technical depth to reader experience level
Neutral perspective: Present honest pros/cons rather than declaring winners
Use case focus: Recommend tools based on specific scenarios and needs
Feature depth: Go beyond feature lists to explain practical implications
Goal understanding: Consider each product’s primary purpose and strengths
Success requires staying objective, providing detailed feature analysis, and guiding readers toward the right choice for their specific situation rather than pushing a single “best” option.
There are a few common types you can choose from when writing technical articles. Maybe you want to share knowledge of something specific, which typically means writing either a tutorial or guide, or perhaps you want to take a stance on something specific and end up writing a persuasive piece. It could also be that you want to share knowledge about a set of products or tools within a certain category, and you’ll be writing a roundup.
In that last scenario, you could also be writing a comparison article instead. You may wonder how a comparison article is different than a roundup, but there are indeed some subtle differences, which will be covered in this article. On top of that we’ll also be looking at some of the reasons you even want to write a technical comparison in the first place, and tips for making it a great one.
Why Write Technical Comparisons
Before you start on anything, it’s always important to understand the reasoning behind it, this is true for writing articles as well. As mentioned in the introduction there are typically five distinct content types that you can choose from, why should you be choosing a comparison specifically? Here are a few reasons why.
1. SEO (Search Engine Optimization)
This is a goal that is shared among pretty much all the different content types, and SEO in and of itself is not specific to comparisons. However, comparisons are treated a bit differently in terms of SEO, when it comes to giving them a title. Comparisons will typically have a title resembling “X vs Y”, which is very akin to what readers are searching for. This makes it likely that the title of a comparison article will match a reader’s query word for word, if you have written one that matches the exact tools they are looking at.
2. Comparing Yourself to Competitors
Writing a comparison article is a great way to showcase why and how your product is better than your competitors. It’s not unusual that companies have a landing page where they put attention on the core features that set their product apart, but a landing page can only contain so much information.
A good comparison article will go into detail with the products and flesh out the differences that set them apart. In some cases, a comparison article will simply act as a fleshed-out version of a well-constructed landing page.
3. Spreading/Proving Knowledge in the Field
A comparison article isn’t always going to be about your product specifically. You can also use them effectively to prove that you have knowledge in the field. Let’s say that you have a company that helps developers monitor their infrastructure. Then it would make sense to create a series of articles where you compare different monitoring solutions in the industry.
This will bring readers to your blog, even if they’re not looking for your product specifically. This is where you can then introduce the reader to your product in the form of a CTA.
Tips for Writing Technical Comparisons
Now that you know more about why you would even want to write comparisons in the first place, it’s time to get some tips on what makes a good comparison stand out.
1. Know Your Audience
Just like with the point on SEO, this is not something that’s very specific to technical comparisons, this is common no matter what article type you are writing. However, it’s worth mentioning anyway as this is crucial to a good article.
You can get very specific with who your audience is, but mainly you want to think about the experience level of the audience you are targeting. If you are targeting an audience of complete beginners, you need to remember that most points you talk about have to be followed by an explanation of why it’s important. This should also be the case when it’s an experienced audience, the varying factor is how much detail you can include.
2. Remember the Reasoning
Especially when you are writing a comparison, you need to remember the reasoning for what you write. There are many sites out there that will automatically pull a feature list of different products and present them in a table view. This can be useful if you know what you are looking for, but most of the time readers want to know why it’s better to use X technology over Y technology. That is something you won’t get from a table view of features.
3. Know the Goal of the Products
Once you start writing a comparison article, it’s easy to lose track of what the goal of the products is. Say you are writing an article comparing two products that can both analyze log statements. One of them is built for this exact purpose, and the other has had it added to an existing suite of features.
It’s important when writing a comparison that you never criticize any of the products you’re writing about. If a specific feature isn’t the core part of the product, that is worth mentioning, as it may then be better in other aspects. A good comparison doesn’t say “Use tool X because it’s the best”. A good comparison says “Use tool X if this is your use case, and use tool Y if this is your use case”. This is especially true if your product is part of the comparison, as it can otherwise quickly come off as a biased opinion.
4. Flesh out the Features
As stated earlier, a comparison can be thought of as a fleshed-out version of a good landing page. In a comparison, you have the ability to flesh out the different features more and cover exactly what aspects are good and which are not. This is again one of the reasons readers go to look at comparison articles, rather than a simple table view of features.
Conclusion
In the end, the main thing to think about when writing a comparison is to stay neutral. Some writers tend to think that a comparison article is about finding the best product, which is not quite true. It’s about arming the reader with enough knowledge that they can make that decision themselves, and in some cases, gently nudging the reader in the direction you want them in.
Hopefully, this helps you understand a bit better what it means to write a comparison, and why you would want to choose this content type over others. If you are looking for more opportunities to write these types of articles you can apply to our writer pool. Or, if you’re a business and you want help in producing these sorts of articles for you, you can schedule a discovery call.
If you’ve spent even just a small amount of time in the engineering world, you will have come across Markdown. It’s quickly become the de-facto standard for any writing project within engineering. Many favor writing in Markdown, whether it be a simple README file to explain what a certain application does or complete documentation. It makes it easy to write readable, styled documents that you can read directly or after parsing through a Markdown-to-HTML converter.
If you don’t know what Markdown is, or if you’ve only heard of it, it may seem confusing how a tool for writing can do these things and be held in such high regard by an entire community. This blog post will dive a bit deeper into why Markdown was developed, what exactly it is, and why you should use it. To give you an idea of how you can use Markdown, even this blog post is done in Markdown writing.
A Brief History of Markdown
As with anything, to truly understand it, you need to understand why it exists. This applies when understanding how to use Markdown.
Way back when people were first starting to use written text on computers, people quickly wanted a way to express themselves. Whether by emphasizing some words more than others or writing ordered lists using hyphens, the simple plain text didn’t cut it. One of the earliest examples of text formatting was to surround a word with asterisks to make it italicized, something that’s still in use in Markdown writing today.
As time went on and websites became more popular, pure black text on a white background wasn’t good enough. It had to be styled, which you could do with a combination of HTML and CSS. However, writing the tags needed in HTML added a lot of extra work, so WYSIWYG editors started appearing. What You See Is What You Get. Editors that provided writers with buttons to help format text.
This worked great and is still in use in many places today. However, some weren’t satisfied. The fact that you couldn’t simply be writing text but instead had to use either complicated keyboard shortcuts, or point-and-click interfaces, was a nuisance for many. This was when people started creating alternatives. Ways of writing text that could then be directly converted into HTML. Using the old email conversations as inspiration, these tools wanted it to be possible to create a styled article, using only characters found on your keyboard like asterisks, hyphens, underscores, etc.
Many alternatives were created, like atx and textile, but Markdown became the one widely used in the end. It allowed writers to write more naturally, not thinking about removing their hands from the keyboard, using only regular characters for the formatting, while still being readable in its plain-text format. You can read this article to learn more about the history.
Why Use Markdown?
The history should indicate why Markdown became popular and why it’s still in use today. Over time many people have used rich text editors, so-called WYSIWYG editors, where the quickest way to format your text is by using keyboard shortcuts or buttons. This takes focus away from writing. As stated earlier, Markdown uses familiar characters to format your text, making it possible for formatting to become just as much second nature as the writing itself.
So, it makes writing and formatting easier, but that’s far from the only reason to start using Markdown. It also makes your written content more flexible. As stated in the introduction, this article is written using Markdown. You see the written text after it’s been converted into HTML, making the headers and the text styled in a specific way. If you were to take the original Markdown text and paste it into another editor, it would look slightly different. The formatting will be the same, meaning italicized words will still be italicized, but the headers may be different in size, color, or even font.
The formatting stays the same, but the style can be changed. That’s the power of Markdown. That is why we use it here at Draft.dev when working with clients and writers. It allows us to not worry about how a paragraph needs to be styled according to a specific client’s blog. It will enable us to stay focused on the quality of the content instead of the design.
Writing in Markdown
Now that you’re, hopefully, convinced that writing in Markdown is the easiest way to produce flexible content, it’s time to learn it. Luckily, one of the significant strengths in learning Markdown is how quick it is to pick it up. Writing headers is done by using hashtags. For example, this section is written like so:
# Writing with Markdown
Now that...
If you want to make subheaders, it’s just a matter of adding more hashtags.
# Header 1
## Header 2
### Header 3
That’s how easy Markdown makes the process of creating new sections. Styling text within a single section is a matter of surrounding the words with the correct characters. The following section:
> This sentence contains a _italized_ word
> This sentence contains a **bold** word
> This sentence contains a [url](https://example.com)
Turns into the following, where the > characters create the indentation:
As you can see, the characters in using Markdown may seem a bit weird at first, but once you’ve gotten used to them, you can quickly write formatted text. To learn markdown in more detail, you can use this interactive tutorial. You may have noticed that italicizing a word was done differently in this example than shown earlier in the article. Markdown offers many different ways of doing the same thing, allowing the writer to express themselves the way that fits them best.
Markdown Editor
Learning how to use Markdown is one thing. Using it is another. However, the path between the points is not long. While a part of why Markdown is powerful is that it can be written in any text editor (even Notepad), it’s often helpful to use an editor that supports Markdown, enabling you to get a live preview of what you are writing. When writing this blog post, I’m currently using VSCode with a few helpful Markdown extensions installed.
If you don’t want to use VSCode, there are many other great alternatives, many even online. When I first started writing Markdown, I was a heavy user of Dillinger. It’s a straightforward interface, and you can begin writing in Markdown immediately.
Over time, I’ve found another tool called StackEdit which I prefer. I think the UI is smoother, and I like the preview function more. I’m mentioning both of them as everyone is different, and some will prefer one over the other. However, those two options are among the most popular to use.
Conclusion
That’s really all you need to know about Markdown writing and how to use it. It’s a handy tool to have in your toolbelt, yet it’s not so complicated that you need to spend weeks learning it. I can only recommend that you start to learn Markdown by writing your content in it wherever possible. It’s universal, and once you know how to write Markdown, you’ll be surprised to find how many places it can be used.
If your core audience is technical, you already know that your readers won’t pay attention to any content that’s not written by subject matter experts.
Your audience needs to know that your company understands the industry and its particular niche in it. However, this prerequisite can put a bit of a hiccup in your content publishing pipeline: subject matter experts aren’t always expert writers.
Fortunately, with a robust editing process in place, they don’t have to be. At the end of your content workflow, your writers should feel confident that their point is being conveyed clearly and efficiently, and your audience should be able to trust that your content is easy to understand and correct.
For example, Draft.dev’s multistage editorial process includes at least three rounds of edits before content reaches the final audience:
Technical review
Developmental edit
Copy edit
And sometimes even two more:
Author review
Stakeholder revisions
Want to develop your own editorial process for your technical blog? I’ll guide you through all five of our steps here at Draft.dev in detail. By the end of this article, you should be well on your way to a thorough and efficient edit that you can recreate with each new post.
1. The Technical Review: the Red Flag
Edits should always progress from the biggest picture to the finest detail. There’s no point worrying if commas are in the right place when the piece has huge inaccuracies.
The first person who looks over a draft should be reading for technical accuracy. They don’t have to be as deeply expert as the writer, but they should be able to tell if any gaps need to be clarified for readers or, heaven forbid, the writer has oversold their expertise and is in over their head.
This does not mean “I would have written it differently, therefore it’s wrong” or “their grammar is sloppy, so the whole thing needs to be redone.” Your technical review should answer these questions and these questions only:
Is the content inaccurate or misleading?
Does the target demographic need more or less information to absorb the point of the content?
If the answer to one or both of these questions is yes, then this article may need to go back to the writer immediately. You should have someone in your editorial pipeline able to make this judgment call.
If the answer to both questions is no, then proceed to a more fine-grained edit.
2. The Developmental Edit: the Architect
I know I said “fine-grained,” but a developmental edit is still a rather big picture edit. Here, you’re examining the content for efficient organization.
Does the information flow well? Do paragraphs need to be moved around? Are readers helped through the article with a clear introduction and headers that make sense? Does the article conclude in a way that answers any questions that have been posed? There can also be some overlap with a technical review here—is the article speaking to the main point? Does the title reflect the focus of the piece?
Experienced writers working with experienced editors may not need to address the article again at this point. It’s very possible that they’ve nailed the subject matter, and the editor was able to make any necessary adjustments themselves.
However, a developmental edit can definitely poke holes in an article. Perhaps wordy sentences deflate into nothing, or a critical section of the proposed outline has been missed. In those cases, the article needs to head back to the writer for an author review.
3. The Author Review: the Checkpoint
An author review is not a complete rewrite (your publishing schedule most likely doesn’t have time for that anyway), so make sure you communicate clearly what you need the writer to focus on at this stage.
Do they need to address a bug in some sample code? Does a screenshot need to be remade? This is the time to ask your writer to address specific changes to the content.
4. The Copy Edit: the Quality Control
When you’re confident that the actual subject matter is as accurate and efficient as it can be, it’s time for a final polish.
A copy edit is a very fine-grained edit—you’re looking for spelling, grammar, capitalization, punctuation, and that’s just a start. If a writer’s first language isn’t the one they’re writing in, your copy edit may need to be a bit broader and take care of some awkward wording.
Don’t forget to run an eye over formatting as well. Are your header styles consistent? Did the writer use italics and bold for emphasis? Do you need author bios to follow a certain style? Having a technical style guide can help, but you still need to check these tiny things here.
Note: Some editors can handle a developmental edit and a copy edit simultaneously, but if the writing is in rough shape, this can be difficult.
5. The Stakeholder Revision: the Stamp of Approval
At Draft.dev, our clients are the final review before publication. The content should be tight enough that they can easily see the big picture and point out any areas where they want more or less information or a different nuance.
We can expect the content to consistently be at that level because each editing stage beforehand is very intentional. Something specific is being addressed at each point. The content is not being aimlessly tossed from person to person to see what they think.
In fact, if you’re handling your content in-house, you should avoid having reviews done by everyone from the CEO to the marketing VIP to the tech lead. This is expensive in resources—hours and wages and lost progress on other projects—and it usually ends up diluting your message.
The phrase “too many cooks spoil the broth” is highly applicable when it comes to producing a piece for publication. If you pass your content around to everyone with an opinion, you’ll never publish it (and after everyone’s put their mark on it, you probably wouldn’t want to).
But Remember…Start with Good Writing
To recap, you can make your technical content publishing pipeline a lot more painless and more consistent with a solid editing process in place. Put someone in charge of your content. Give them the authority to call a piece finished. Make sure your process is repeatable so there’s no wondering about “who needs to see this next.”
Of course, it helps to remember that an excellent writer leads to an excellent edit. Going back to our cooking analogy, you can rescue a lot of bland dishes with good seasoning, but you can’t save something that’s burned beyond recognition.
That’s why at Draft.dev, we vet our subject matter experts and use an objective rubric so you don’t have to, and then we put their work through our multistage edits.
It’s not easy to build a consistent, reliable content publishing process when it’s not your core business; you can always find room on our calendar to talk about whether or not Draft.dev is a good solution for your technical content creation.
TL;DR: Technical roundups are structured list articles that curate the best tools, blogs, frameworks, or resources within specific technical categories. Unlike tutorials or guides that teach implementation, roundups provide curated recommendations with brief descriptions and ratings to help developers discover and evaluate options.
Key elements of successful technical roundups:
Clear audience targeting: Define whether writing for beginners or experienced developers
In-depth research: Go beyond surface-level to provide authoritative recommendations
Structured format: Use consistent descriptions, ratings, and visual elements
Strategic promotion: Leverage social sharing and mention notifications
Authentic value: Balance promotional goals with genuine utility for readers
Success requires combining comprehensive research with clear organization, authentic recommendations, and strategic distribution to maximize reach and engagement within technical communities.
What is a technical roundup? Some people call them listicles, since that’s their general format: a list of the best and most useful blogs, frameworks, tools, and so on. Think the best Python blogs or the best computer science blogs, for example. It’s a popular article format for a reason. A roundup offers a short, convenient, and well-structured guide to a variety of topics. A good one gives readers a clear understanding of the subject matter, often with some sort of rating or a scoring system indicating the value of each resource.
We write a lot of useful roundups for our clients at Draft.dev, so in this guide, I’ll provide some insight as to why technical roundups are valuable and how to write one that’s solid.
Why Write a Technical Roundup?
Of course, popularity and simplicity aren’t the only reasons why people create roundups. Let’s talk about the more practical and business-related reasons you might want to create a technical listicle.
Showcase Your Product
Any marketer can tell you that promoting a product can be as hard and tedious as building and producing it. Publishing a roundup of, say, tools compatible with your SaaS is a great way to illustrate the broad usefulness of your product. It’s possible to be even more straightforward and include your product in a listicle with your competitors, though you’ll need to take care that you’re honest and aboveboard in your treatment of the other products.
Readers will generally be sophisticated enough to sniff out flat-out advertising, and the goal of a listicle should be, on some level at least, to inform more than sell. A technical roundup that deals honestly and transparently with its subject is a great way to build trust in your company’s services.
Enhance Your SEO
Be the most authoritative source, provide the most credible, researched and in-depth information. If the best format for your content is a listicle, that’s fine. But don’t write a listicle without thinking of all the other factors that matter to SEO. – SpiderGroupUK, Reddit
Roundups tend to perform well on search engines because the click-through rate is high. They tend to answer common queries like, “what are the best tools for continuous integration?” or “what are the best Ruby blogs?” So, when a searcher sees a list post that answers their question, they’re likely to click.
As a company, you can harness these click-throughs to get more eyes on your product. In addition to suggesting the top solutions or tools for a problem, roundups often note which options work best for specific use cases, helping readers narrow their focus and isolate a path forward.
Promote Social Media Sharing
When you read a great piece of content, you want to share it with friends and family so they can read it too. However, if you post a long editorial on a heavy subject, you’re probably not going to get many interactions…If you post a listicle on the same subject, you’re much more likely to get comments and shares. – Kristy Snyder, Copypress
Another trick is that people love to share lists they’re mentioned in. Roundups that include solid products, trusted bloggers, and promising startups are easy for those parties to then share on their own social media and newsletters. Organic distribution like that can mean attention from channels you may not have had reach into before.
Hone Your Own Skills
I think we can all agree that the world of tech is fast-moving, hectic even. To be a good engineer, you need to try to stay on top of everything that’s going on in your corner of the industry. Writing a roundup is a great way to pick up the latest news, feel out new trends, and deepen your study of topics you find interesting.
In writing a good, well-researched roundup, you’re going to have to sift through marketing fluff, read detailed reviews, and dig deep into the documentation. Most other engineers won’t have that level of knowledge on the topic.
How to Write a Great Technical Roundup
Of course, it helps to have in-depth knowledge of your field, but that in itself isn’t enough to write a solid listicle. Let’s go over some best practices for crafting a technical roundup.
Think About Your Audience
Before you even begin to gather material for your roundup, you need to know who you want to read it. Is your target demographic software engineers or do you want to reach a more general audience? How familiar do you expect your readers to be with the topic you’re going to cover?
How you answer those questions will determine the depth of your research, the length of the article, even the tone and vocabulary you use. For example, if your site is devoted to backend production, a roundup like “10 Best Ways to Debug in Python” would be appropriate. Knowing what your audience is looking for will go a long way in helping you create a roundup that addresses their specific needs.
Be Picky About Your Research
When you feel confident that you know who your audience is, it’s time to choose material for your roundup. Do your research, and take the time to do it well! You need to display more than a surface-level knowledge of the topic; smart readers can smell hastily thrown-together listicles from a mile away.
For a few examples of well-researched technical roundups, check out:
The Many Roles of a Startup CTO: More of a business-oriented roundup, this listicle offers clarity into the multi-task reality of a startup and offers recommendations for more resources, as well as a video for visual learners.
The Best DevOps Blogs: This is a good example of a scored blog, with list items organized according to writing quality, consistency, longevity, technical depth, and usefulness.
Pay Attention to the Structure
One of the main attractions of a roundup is its reliable structure: a list of best tools or blogs or methods, each item accompanied by a short description and an explanation for why you recommend it. Do you want to score each item for easy reading comprehension? Consider what qualities your readers will be most interested to know about each item in your listicle, and rate them accordingly.
Also, don’t forget to include some screenshots—it breaks up your long read into smaller pieces which make the whole article more readable.
Be Intentional About Your Style
The tone and vocabulary you write with will have a definite impact on how your piece comes across. Consider how it matches with the tone of your company overall—are you more formal or more casual? Do you want to be seen as authoritative or edgy or laid-back? Now consider that general perception against the backdrop of the specific listicle you want to pull together. Is this topic better served by sticking to just the facts, or do you want to be more opinionated and expository? Do you want to take the time to define everything and produce, say, a 3,000-word article, or would it be better to keep things short and sweet and rely on readers to look up things on their own? Consider the main goal of your roundup and adjust your voice accordingly.
Even a good roundup needs promotion to get noticed. No one will read it if you don’t show your work to the world, so this is not the occasion to be modest. Craft Tweets, post on Facebook, add it to LinkedIn, and don’t forget to go beyond social media! Consider submitting to relevant newsletters and forums (though the key word there is relevant. Don’t spam these places if you’d like to have a chance of promoting there again). A sincere, intentional approach to promoting your listicle will go a long way in increasing your audience.
Writing, publishing, and promoting a technical roundup can be a fairly simple first step toward marketing your product, promoting yourself as a voice of authority, and building trust with the audience you want to reach. Remember to do your research, choose an appropriate voice, and be smart about how you distribute it. Don’t forget to keep an eye out for listicles that others have written for examples of what a good technical roundup should look like.
Write conversationally – Match your natural voice while building concepts gradually.
Prove every point – Support claims with research, quotes, or examples.
Develop ideas iteratively – Test concepts on social media before full articles.
Promote actively – Distribution can increase traffic by 12x or more.
Engineers moving into technical writing should concentrate on regular practice, clear structure, careful editing, and active sharing to develop their skills and connect with their audience effectively.
I recently spoke to the CTO Craft community about building a software engineering team blog. Near the end of our talk, the panel of experts shared some helpful writing tips for software engineers who find it hard to create clear technical content.
Since I started writing online in 2010, my interests have changed, but I have always kept a regular publishing schedule. Most of my work has been unpaid and fueled by passion. However, after launching Draft.dev and shifting to a writing career, I have closely examined what makes good technical content.
Most of my writing has been unpaid work done purely because the topic interested me, but in the past year since I started Draft.dev and turned writing into a career, I’ve started to think more critically about what makes good technical content.
In this post, I’ll share my tips for tech professionals who want to enhance their technical writing skills. While these tips are useful for everyone, they are especially aimed at software developers, based on my experience.
This is a long post, so if you’d like to hop around, here’s what I’ll cover:
What Are the Key Differences Between Technical Writing and Other Forms of Writing?
Technical writing is distinct in several ways from other forms of writing, such as creative writing and journalistic writing.
Definitions:
Technical Writing: This is a specialized form of writing that conveys complex information clearly and concisely, often in fields like engineering, IT, and science. It focuses on delivering instructions, documentation, and user manuals.
Creative Writing: In contrast, creative writing emphasizes artistic expression and storytelling, often found in novels, poetry, and scripts.
Key Differences:
Purpose: The primary goal of technical writing is to inform or instruct the reader, ensuring they can understand and apply the information effectively. Creative writing, however, aims to entertain or provoke thought, often prioritizing narrative and emotional engagement over clarity.
Structure: Technical writing typically follows a clear, logical structure with headings, bullet points, and numbered lists to enhance readability. Creative writing may adopt a more fluid structure, allowing for varied pacing and style to enhance the narrative.
Language and Tone: Technical writing uses precise, unambiguous language and a formal tone to avoid misinterpretation. Creative writing often employs figurative language, dialogue, and a more personal tone to engage the reader’s emotions.
Actionable Outcomes: To apply these differences in your own writing, consider the following steps:
Identify Your Audience: Determine whether your primary goal is to inform or entertain. Tailor your writing style accordingly.
Choose Your Structure: If your aim is to provide instructions or technical information, use clear headings and bullet points. For storytelling, focus on narrative flow and character development.
Adjust Your Language: Use straightforward language for technical documents to ensure clarity. In creative pieces, feel free to explore metaphors and varied sentence structures to enhance engagement.
By understanding these distinctions and applying them thoughtfully, you can enhance your writing effectiveness across different contexts.
1. Why Shouldn’t I Expect to Be Good at Writing Right Away?
The skill and ability involved in writing sentences is generally underrated, and assumed to be a much more universal capacity than it really is…Most people know that they couldn’t write even a very bad song, or paint a picture, and understand their limits in that regard. On the other hand, everybody can write prose after some fashion, so it is not quite clear to them that they don’t actually have the ability to do it to a professional standard. That ability is quite a rare one. – Philip Hensher, Professor of Creative Writing at the University of Exeter
By the time you graduate from high school, you’ve probably spent a fair amount of time writing. You might think you’re pretty good at it, but as soon as you dust off that old keyboard and start putting the proverbial pen to paper, you’ll quickly realize that writing is harder than it looks.
The Gap
The problem here is what Ira Glass calls “the gap:”
All of us who do creative work … we get into it because we have good taste. But it’s like there’s a gap, that for the first couple years that you’re making stuff, what you’re making isn’t so good, OK? It’s not that great. It’s really not that great. It’s trying to be good, it has ambition to be good, but it’s not quite that good. But your taste — the thing that got you into the game — your taste is still killer, and your taste is good enough that you can tell that what you’re making is kind of a disappointment to you. – Ira Glass
This gap is especially problematic for technical content writers like software engineers. Theamount of information you have in your head is exponentially more than the amount you’ll be able to get onto a page in an hour. Software engineers who are new at writing often experience frustration because they know what they want to say, but lack the language, typing speed, or organizational skills to express it well.
Your first 100 blogs, videos, posts, Tweets, lives, podcasts, creations will probably all be rubbish.
Get over that and get to it, get past that first 100.
Hardly anyone will see it anyways, it’s practice for when they do.
Understanding this gap is crucial as you enter the world of technical writing. Just remember that everyone starts out as a beginner, and you can’t create skills overnight. Embrace the process, and allow yourself the grace to grow through practice.
How Can I Find a Good Editor to Improve My Writing?
Once you accept the fact that your early writing won’t be that good, it takes a weight off, but how do you actually start to get better?
If you aren’t ready to submit work to an editor yet, you can always enlist a friend for help. Even non-technical editors can help you improve your technical content writing. The best editors will be able to tell you when an idea you present doesn’t make sense or the piece is poorly organized.
What Are the Common Mistakes to Avoid in Technical Content Writing?
When writing technical content, it’s easy to fall into common pitfalls. Here are some mistakes to avoid:
Overly Complex Language: Using jargon or technical terms without explanation can alienate readers.
Neglecting the Audience: Failing to consider the knowledge level of your audience can lead to content that is either too simplistic or too advanced.
Lack of Structure: Not organizing content logically can confuse readers, especially readers who are used to reading technical documentation. Always use outlines and headings to guide them through your piece efficiently.
Ignoring Feedback: Not seeking or incorporating feedback can hinder improvement. Always be open to constructive criticism.
Skipping the Editing Process: Failing to revise and edit can leave errors in your writing. Always allocate time for thorough editing.
2. How Can I Stay Consistent and Push Through the Early stages of My Project?
Many great projects go through a stage early on where they don’t seem very impressive, even to their creators. You have to push through this stage to reach the great work that lies beyond. But many people don’t. Most people don’t even reach the stage of making something they’re embarrassed by, let alone continue past it. They’re too frightened even to start. – Paul Graham
The key to getting better at writing is to do it consistently, even if you’re not that good at first.
Write Every Day
One way to write more is to write every day.
In 2017, I made a commitment to write every day. I didn’t hit that goal, but the year was still my most productive year as a writer to date. I wrote a book, updated many old posts on my personal blog, got paid to write a few pieces as a freelancer, and contributed to my company’s blog a few times. I don’t keep a word count (to me, that’s sort of like tracking how many lines of code you write), but I’m sure it was over 50,000 words.
Measuring programming progress by lines of code is like measuring aircraft building progress by weight. – Bill Gates
💡On average, it takes 66 days to form a new habit. There’s 65 left until 2021, so how about we start early on those New Year Resolutions?
I’ll start: I’m trying to publish content consistently, so I’ll try to write a minimum of 100 words a day for the remainder of the year. pic.twitter.com/M0dHrJ36ef
I don’t think you have to write every day forever to get better, but it will dramatically accelerate the speed at which you improve.
Block Time for Writing
Because of technology, some people feel distracted – they can’t focus, that they can’t pay attention to what’s in front of them because their minds keep jumping around. They aren’t getting their work done; they’re not paying attention to their kids. – Gretchen Ruben
A few months ago, I realized I wasn’t getting as many of the important things done as I would have liked. I started blocking my time off each week in 4-hour increments, focused on one thing I want to get done. Now my calendar looks like this each week:
I want to devote 8-12 hours per week to writing consistently, so I literally block my entire Thursday and Sunday off for it. During blocks where I have meetings, I focus on sales and marketing tasks that are quicker and don’t require the same level of flow.
If you don’t do this, it’s way too easy to fall into the trap of endlessly checking email, scrolling through your Twitter feed, or playing Candy Crush instead of creating great content.
Deliberate Practice
While regular practice might include mindless repetitions, deliberate practice requires focused attention and is conducted with the specific goal of improving performance…In the beginning, showing up and putting in your reps is the most important thing. But after a while we begin to carelessly overlook small errors and miss daily opportunities for improvement. – James Clear
Once you make writing a habit, you have to figure out how to actively improve your craft. Creating great technical content requires focused practice with increasingly difficult tasks.
The mental model I like is called the zone of proximal development. The idea is that you will learn the most by maximizing your time doing tasks that are just outside your level of mastery.
James Clear includes several examples in his essay on deliberate practice, but the most relevant to writing technical content is Benjamin Franklin’s story:
When he was a teenager, Benjamin Franklin was criticized by his father for his poor writing abilities. Unlike most teenagers, young Ben took his father’s advice seriously and vowed to improve his writing skills.
He began by finding a publication written by some of the best authors of his day. Then, Franklin went through each article line by line and wrote down the meaning of every sentence. Next, he rewrote each article in his own words and then compared his version to the original…Franklin realized his vocabulary held him back from better writing, and so he focused intensely on that area.
Deliberate practice always follows the same pattern: break the overall process down into parts, identify your weaknesses, test new strategies for each section, and then integrate your learning into the overall process.
The great thing for people wanting to be technical content writers is that breaking down and rewriting existing tutorials is a fantastic way to both learn the technology and hone your craft as a writer.
Don’t Overcomplicate It
Our life is frittered away by detail…Simplify, simplify. – Henry David Thoreau
I really appreciate this diagram on writing by Doug Arcuri, but I think it overcomplicates the process for most new writers. While organization is important in writing (more on that in the next section), don’t let it overwhelm you.
The most important part is to start.
3. Writing is Organizing
The first two points above have been a little bit philosophical, but I want to spend the rest of this post getting tactical. I’m going to start with organization.
Most new writers don’t realize that organization is such an important part of writing. This is especially true in technical content writing where you’re trying to convey or teach a topic to a diverse audience. You want to give new readers the ability to build up to difficult topics while giving experienced readers the ability to skip to the parts they care about. The only way to serve such diverse readers is to invest time in organizing.
Start Every Piece With an Outline
Your 7th grade English teacher probably taught you to start with an outline, but by the time you got to 12th grade, you probably skipped that step to save time. Some writers think they know the topic well enough to skip outlining, but I can tell you it’s a really bad idea.
The outlining phase is where you prioritize ideas, identify weaknesses in your knowledge, and crystalize your main points.
I’ve also found that starting from an outline speeds up the writing process dramatically. With a well-thought-out outline, writing becomes the mere act of connecting the dots. Without one, it’s an unintelligible mess.
How Specific Should Your Outline Be?
My rule of thumb is to write an outline that covers all the H2 and H3 tags on the page.
Don’t stick to the outline like a rule-book; it’s more like a starting point. I often discover new ideas as I’m writing and need to move things around to accommodate them.
If you’re writing technical tutorials, you should create the demo application and outline the steps before you start writing the rest of the content. If you do it this way, you’ll find the writing part is very quick. It often takes me less than two hours to finish a 1500-word tutorial after I’ve written the code and outline.
Organization Methods
If you’re a new technical content writer, it’s probably hard to know how to start organizing technical content. There are four commonly accepted methods that I push people towards:
Chronological – Tutorials are typically organized from first step to last.
Importance – When presenting multiple options or comparing factors between tools, it’s usually a good idea to order them by importance.
Problem and Solution – I like framing posts around problems and solutions when they’re aimed at technical decision-makers.
There are probably optimal organizational systems for different kinds of posts, but honestly, just having any system will make your writing better than most.
4. Self-Editing
The Importance of Self-Editing
Self-editing is a crucial skill for any writer. It allows you to refine your content, ensuring clarity and coherence before it reaches your audience.
Here are some tips for effective self-editing:
Take a break after writing before you start editing.
Read your content out loud to catch awkward phrasing.
Look for common mistakes in grammar and punctuation.
5. How to Effectively Edit Technical Content
Editing technical content requires a specific focus on clarity, accuracy, and audience understanding. Here are some strategies:
Understand Your Audience:Tailor your language and explanations to the knowledge level of your readers.
Check for Technical Accuracy: Verify all technical details, ensuring they are correct and up-to-date.
Simplify Complex Ideas: Break down complex concepts into simpler parts, using analogies where appropriate.
Use Visual Aids: Incorporate diagrams, charts, or screenshots to enhance understanding.
Seek Feedback: Have peers review your content for clarity and technical accuracy. By following these guidelines, you can enhance the quality of your technical writing and ensure it effectively communicates your ideas.
6. Write as You Speak
Your writing should sound like you. Your vocabulary, your cadence, your syntax, your dialect. Your verbal idiosyncrasies. Friends and colleagues should be able to hear your voice in their heads as they read. Communication is a relationship, and to develop an authentic relationship with your reader, your writing – like your speech – should convey not only your opinion, but also a bit of your personality. – Sarah Chauncey
I used to write technical documentation for Siemens medical imaging equipment, so I read and wrote a lot of dry documentation. That said, not all technical content needs to read like a user manual.
Blogs are great because they give you carte blanche to create your own voice. That said, adopting a specific voice for writing is really hard, so new writers should keep it simple and write like they speak.
Build Up to Each Concept
The other problem that subject matter experts encounter when they start writing is they forget most readers won’t be as knowledgeable as they are. Good technical writing and content is correct and uses industry-standard terms without overwhelming new readers. The trick is to build up to each concept as you deliver it.
The way I do this is by creating an outline that starts with no assumptions. For example, if I were writing an article about deploying Python workloads to Kubernetes, here’s what I’d start with:
What is Python?
What is Kubernetes?
What is a Kubernetes cluster?
What are the relationships between Kubernetes and containers?
Why deploy Python to Kubernetes?
How to deploy a Python web application to Kubernetes:
What is a workload in Kubernetes?
How do you prepare a Python application for Kubernetes?
While the focus of the article is on deploying a Python application to Kubernetes, I’d probably devote 2-3 paragraphs explaining the basic terminology. Then, I’d link readers to more comprehensive resources (like the documentation) to let them explore these topics in more detail.
This might seem like overkill, but an experienced reader will simply use the headers to skip down to the portion of the technical content they need. This extra context will only help people who are new to Python or Kubernetes ramp up to the meat of the article.
It’s admittedly hard to do this without shaving the yak, but you’ll get better at it the more you write and get feedback on your writing.
Can You Be Too Casual?
Most writers tend to be too formal, but since I started editing more in the past year, I’ve realized that some fall towards the other extreme instead.
The important thing is to know your audience and the publication you’re writing for. If it’s your personal blog, you can be as casual as you want. If it’s for your company’s blog, you might want to make it a little more formal. The same goes for a technical writing blog.
My rule of thumb when writing technical content is to pretend you’re in a business meeting. If you wouldn’t say it in front of your boss, you shouldn’t write it in public.
Self-Editing
Writing without revising is the literary equivalent of waltzing gaily out of the house in your underwear. – Patricia Fuller
Editing is an entirely different skill than writing. I used to assume that anyone who could write could also edit, but I’ve since backed off that view. Writing is the big-picture process of organizing, researching, and molding ideas together. Editing is getting the nitty-gritty details right and asking if this whole thing even makes sense.
That said, good writers do at least a little bit of self-editing.
I do two things for every post I write before I hit publish:
Wait a few hours, then read it out loud – This helps me catch logical omissions and poor organization. Waiting a few hours helps me get a fresh perspective that I couldn’t get right away.
Run it through Grammarly – This helps me catch little details, misspellings, and wordy sentences.
7. Prove Your Point
The best way to show that a stick is crooked is not to argue about it or to spend time denouncing it, but to lay a straight stick alongside it. – D.L. Moody
One of the few things I remember from my high school English class was my teacher’s insistence that every claim be backed up by a source. For some reason, that stuck in my future engineer’s brain, and it’s become a great asset now that I write for a living.
Good technical writing articles must be correct, so I pretend that my readers are all ornery skeptics hoping to poke holes in every statement I make.
There are three ways to add evidence to support your claims as a writer:
Research – Academic research typically has the highest bar, but business surveys or secondary research are sufficient for most informal technical content. Unfortunately, a lot of people don’t verify the research they use very carefully. This leads to a lot of technical content backed up by dubious claims taken out of context.
Quotes – I like quotes for a few reasons. They help break up long blocks of text by injecting an authoritative source, and they can add the weight of celebrity to your ideas. Again, be careful with verifying quotes.
Examples – People really like stories. While this can get naive readers into trouble, it’s helpful ammunition for writers. Personal experience or relevant anecdotes also help strengthen your claims.
8. Invest in Interesting Ideas
Do not worry. You have always written before and you will write now. All you have to do is write one true sentence. Write the truest sentence that you know. – Ernest Hemingway, A Moveable Feast
I’ve written about these topics already, but something I never realized until this year was that as a writer, you can write about the same topic twice.
In fact, the best writers come back to the same few ideas repeatedly throughout their careers.
The key is identifying all of the smaller components that go into the same topic and then fleshing each of them out until they are large enough to make up a complete piece of writing on their own. – Louise Truscott
I can’t remember where I first heard this idea, but lately, I’ve been trying out ideas on Twitter. If they pick up a little traction, I’ll bring them into conversations and keep an eye out for other writing on the topic.
If it seems like others are interested in the idea, I’ll write a short bit about the topic in my email newsletter or on Reddit.
Finally, when I’ve run the idea through a few people and really honed it, I’ll compose a blog post on the topic. Here’s how this worked for my post on experts I mentioned above:
The idea started with a few tweets. People responded to them, and I refined the idea during a couple of conversations and a podcast I recorded for a friend. I read more from other writers on similar topics and eventually summarized my thoughts in my weekly email newsletter. Finally, I constructed the final product: a 2500-word blog post called The Danger in Listening to Experts.
Nobody is Truly Original
Written content doesn’t have to be completely original. A lot of writers get paralyzed when they can’t come up with a novel idea. Andy Haskell talked about his perfectionist tendencies in a blog post earlier this year:
My perfectionist tendencies made it take forever to get a new post out the door, and caused me to feel like my content was going to be nothing new that people couldn’t already Google for. That narrative in my head left a lot of unfinished blog posts piling up. – Andy Haskell
The truth is that all ideas are really mashups of existing ideas. That doesn’t mean your perspective on a topic won’t contribute to the world. You probably know many things that other software developers don’t know. When you create technical content online, you might just write it in a way that resonates with someone else. The opportunity to teach someone – even if the concept isn’t original – is enough to motivate most writers to power through at least a few blog posts.
Stay Open to Inspiration
Most of what I “write” doesn’t even happen on the page. It happens while I’m away from the computer, when I’m in the line at the grocery store, waiting at the airport, or speaking with friends. – David Perell
Ideas come from without, not within. That means you have to get out into the world if you want to come up with good ideas for technical content.
Software engineers do this by tinkering with new frameworks and languages. Product managers might try new organization tools. Designers might have conversations with artists for inspiration.
9. Tell People
Distribution is the secret of the most successful blogs. Writing well is the cost of entry, but distribution takes you to the top. – David Perell
I’ve been refreshing blog posts on my personal blog for the past couple of months. To illustrate the power of distribution, here’s the traffic on one of my old posts over the past year:
I wasn’t actively promoting the post, but it was bringing in 60-120 pageviews per month thanks to Google searches. In November 2020, I decided to update the post and re-share it on social media. It got some upvotes on Hacker News and Reddit, and ended up bringing in 1204 pageviews that month alone.
Simply sharing this blog post led to a 12x increase in traffic to it over the course of a month. This is why writers should learn to share their content. If you want people to read your work, promoting it is essential.
If you’re looking for a checklist of ways you can promote technical writing blog posts, I put mine up on the internet earlier this year. Every piece of content is different, but this should give you a good starting point.
Final Thoughts
Writing great technical content won’t happen overnight. If you expect to be good at it from the start, you’re likely to be sorely mistaken, but stick with it. Writing is a great way to increase your influence and get noticed for your work.
Once you start writing, build a process for capturing and refining your ideas. Good technical content writing is almost always an amalgamation of existing concepts, but the more you compile these ideas, the better you’ll get.
Finally, tell the world when you write! Your knowledge is valuable, and it’s very rewarding to have people share and learn from your content.
TL;DR: Technical tutorials are problem-solving articles that teach developers how to implement specific solutions using particular technologies. Unlike comprehensive guides or reference documentation, they provide step-by-step instructions with real-world context and working code examples. Well-crafted technical tutorials can drive significant traffic while establishing technical authority.
Essential elements of effective technical tutorials:
Context-driven approach: Explain “why” before “how” with real-world use cases
Structured progression: Strong intro/conclusion with logical step-by-step flow
Working code examples: Digestible snippets with explanations and proper formatting
Problem-solution focus: Address specific challenges developers face daily
Success requires combining technical accuracy with clear communication, providing context for each step, and ensuring readers can implement the solution independently after reading.
Technical tutorials offer compact lessons on various technical subjects from general programming to web development to large scale infrastructure and beyond. They are usually short enough to be digested in one sitting (1500 to 3000 words) and aim to solve a specific problem using a particular technology or set of technologies.
We write a lot of tutorials for software engineers at Draft.dev, so in this guide, I’ll share a little bit of why and how we write technical tutorials.
Why Write Technical Tutorials?
There are several reasons people decide to write technical tutorials. Here are a few of the most common ones:
1. SEO (Search Engine Optimization)
Technical tutorials are a great way to draw traffic to your site. Most engineers spend their day Googling for answers to difficult problems. If you’ve ever worked as a software engineer, you know it can be especially hard to find tutorials that use newer technologies or novel combinations of technology.
If you know the types of things your customers are searching for, you can cater to your content accordingly. For example, a company that offers payment processing services could publish a tutorial about accepting payments in a Node.js app. A hosting company could write about using their platform to deploy a Python workload.
The goal here is to write tutorials that answer common questions so that engineers will find them when they search for the topic on Google.
2. Solidify Your Learning
Studies have shown that teaching a subject can enhance your understanding of the material.
Writing technical tutorials is a great way to boost your learning. Many people think that they can’t write technical articles because they are not an “expert” in the subject matter, but some of the best tutorials are written by writers who are just learning the material themselves.
Writers who are new to a subject are closer to a learner’s mindset, which allows them to anticipate the types of questions a reader might have and fill in gaps they wish were clearer when they first learned the material.
Explaining a complicated topic to others forces you to slow down and question your assumptions. In the end, you will retain the information more completely if you teach others about it.
3. Showcase Your Skills
Like pushing your own projects to GitHub or making pull requests on open-source projects, writing technical tutorials is a great way to showcase your talents to potential employers. Writing gives you the chance to show off some of your code, talk about your decision-making process, and highlight your problem-solving skills.
If you want to stand out as an engineer, build small things and write about them. ✍️
It’s easy to start a big project and never finish it. Instead, bite off something you can do in a weekend and then write a blog post about it.
Building a great software product is hard. Convincing users to use your new product can be even harder.
Having great documentation is important, but you can further entice new users with technical tutorials that showcase your service in real-world projects. This adds context for potential customers who may be new to a particular technology or are unsure if your product is right for their project.
Tips for Writing Great Technical Tutorials
Just because you know a topic well doesn’t mean you’ll crank out a great tutorial on the subject. Here are a few things to keep in mind to help you write informative, engaging, and useful technical tutorials:
1. Know Your Audience
Understanding your reader is crucial to writing a technical tutorial.
Writing is about making choices regarding what to include and what to leave out. You have to decide if you’re going to spend two paragraphs explaining something or simply provide a link to an outside source. You won’t be able to make any of these decisions if you don’t know who you are writing for.
Because of this, it doesn’t go into great detail about setting up a Django app, but it does take great care in laying out the concepts around Amazon S3 and how they integrate with Django in particular. We could say the audience for this article is “experienced Python developers who are relatively new to Amazon S3.”
Before you start your next tutorial, try writing a sentence or two about who your audience is. It will help you stay focused as you write.
2. Provide Context
Don’t tell your reader how without first answering why.
This is where most technical articles fail. They meticulously document steps – download this package, write this code, add this config file, etc. – without ever explaining the purpose of these steps or how they might change under different circumstances.
Steps are how Ikea instructions are written. No one has ever assembled a shelf from Ikea and then turned around and claimed they could build their own from scratch. Sure, I see they used this type of screw, but why? I want my bookshelf to be half as wide and twice as tall. Will it still be stable?
This article about Postgres Views in Ruby on Rails uses a real-world dataset of hockey teams and top scores for its examples.
The writer does a great job adding context to each step, which strengthens the reader’s understanding of the concepts. After finishing the article, the reader doesn’t just know how to build a hockey data view. They leave with an understanding that will allow them to use Postgres views in Ruby on Rails any way they want.
3. Have a Clear Introduction and Conclusion
Readers of technical articles are looking to solve problems and learn new skills quickly. Your introduction should be concise, and it should answer these three questions right away:
What will the reader learn?
What skills will the reader need?
What problem does this technology help solve?
This article about building an SMS reminder tool for teachers explains the problem it’s trying to solve and how it’s going to solve it immediately in the first two paragraphs.
Your conclusion should mirror your introduction and answer the following questions:
What did the reader just learn?
What problem was solved?
What next steps can the reader take if they want to learn more?
A technical edit can help you ensure the tutorial is reader-focused and flows correctly.
4. Provide Code Snippets
It’s always helpful to provide unique code, dependencies, and configuration files that are required for your technical tutorial. You can provide a link to your completed project on GitHub if you want, but you’ll need to be selective about what code you include in the article itself.
A few things to keep in mind as you include code samples:
Break them down into digestible chunks. Don’t provide 80 lines of code and then tell your reader to copy and paste it. Better to choose smaller sections of code that are more digestible, making sure to explain what each line does.
Format your code correctly. Code that isn’t formatted correctly is difficult to read and, therefore, difficult to understand. Find a style guide for the language you’re working in and make sure your code sticks to the standards agreed upon by the community.
Don’t forget about file structure. This usually only applies to large projects, especially when working with React or Ruby on Rails. In these frameworks, the location of your files can affect how and if it runs. It’s sometimes helpful to provide the file name and path at the top of the code snippet in the form of a comment:
# blog/models.py
class Post:
# ...
5. Promote Your Work
A technical tutorial needs an audience.
Sharing your work with others is a great way to find more writing opportunities, so don’t be afraid to promote your tutorials on social media or start an email newsletter. Ask your readers for feedback on what worked and what could have been clearer in your tutorial. Taking feedback is essential to improving your writing skills.
In this article, I broke down some of the reasons you might want to write a technical tutorial. Whether you’re interested in growing your business, advancing your career, or leveling up your skills, writing technical tutorials can offer many advantages.
Finally, I broke down some of the crucial components of useful and informative technical tutorials. If you need help writing technical tutorials or you’d like to work with our team of writers to build content that reaches software engineers, contact us today.
