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.
Are you ready to become a better technical blogger?
Technical blogging is our specialty at Draft.dev, so we invite our best authors to compile their tips for 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.
In the field of technical writing, consistency is crucial because it provides the sense of confidence and continuity that every tech product needs to engage a userbase. Consistency also creates opportunities to build communities around technical documentation.
How do you make your technical documentation more consistent? One of the first steps is to adhere to a technical writing style guide. Itself a piece of documentation, a style guide defines communication standards for any tech document that your business produces, and all of your writers can follow it. It usually covers the voice, structure, and technical conventions (such as the format of the text, audio, and images) used in the documentation.
Since style guides cover so much ground, they can be a chore to create from scratch. Fortunately, many companies have made their own technical writing style guides available publicly so you can analyze their strengths as you create your own style.
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.
While this guide focuses on clarity and quality, there’s also a companion technical best practices tutorial, which offers standards for how writers should discuss the tech they’re writing about (how to write about installation, how to offer troubleshooting tips, and what to do with long scripts).
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 contains valuable information you can use across many contexts, including instructional materials, technical documentation, reference information, training programs, and user interfaces. It also references Merriam-Webster’s Collegiate Dictionary and The Chicago Manual of Style.
The guide covers a wide variety of editing minutiae, including units of measure, technical notation, a large glossary of terms for proper usage, and links to related resources. It also includes tips on writing for an international audience, something that’s especially important to consider in technical writing:
Following international style helps readers with limited English proficiency read what you write. By following international style, you also help translators—human or machine—localize your writing by minimizing the burdens of cultural and customary language usage.
The style guide is managed like a software project, with source code. It includes a set of tests that cover:
The writing and structure of each article
Links in the content
Assets in the content
GitLab’s guide references other technical content guides (Google and Microsoft, also covered in this article) and emphasizes the documentation-first methodology approach of the company. This implies that the technical documentation is the single point of truth for the implementation, usage, and troubleshooting of the product.
The Google developer documentation style guide provides a full set of solid practices for producing technical documents. The guide also acknowledges that many projects under Google’s umbrella might have their own specifics, and it establishes a reference hierarchy that prioritizes the project’s own standards over the common guide.
The guide is very dense and has several sections, so here are a few highlights:
Accessibility: This covers not only the voice and tone of the documents but also keyboard navigation tips, support for screen readers, inclusive language, and the use of HTML for formatting.
Language and grammar: This section establishes common rules for writing. There’s some interesting advice to avoid anthropomorphizing software products and how to use specific verb forms in reference documentation.
Linking: This includes best practices for readable links.
Computer interfaces: This section pays special attention to documentation guides for application programming interfaces (APIs).
Markdown versus HTML: The guide posits that HTML is more expressive than Markdown, even if the second is easier for humans to read.
Names and naming: This section explains naming conventions for file names, domains, trademarks, and more.
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.
Conclusion
After reviewing all the referenced style guides, you may have noticed three common elements:
Know your audience and write for them
Set your own voice
Keep it as simple, short, and clear as possible
This advice is not enough to create a full-fledged style guide, of course, but rules for details like format, glossaries, and standard structures can evolve with time. A good starting point is to take the best parts of the resources available and build your own from there. For more tips, visit the Draft.dev website or 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, deep technical knowledge is 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.
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 writers and reached out to hundreds of others to help us create content for our clients.
Needless to say, we understand technical content at scale, and one of the most fundamental parts of our process is finding great technical writers for hire.
In this post, I’ll share our exact process for finding 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. As our client base grew, 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 writers, but I quickly realized that I didn’t know that many software engineers who also wanted to write blog posts.
The next avenue I tried was Upwork. I’ve had fairly good results hiring other types of freelancers on Upwork, but I just couldn’t find writers who were 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 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 four 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 searches 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 ,
I ran across your piece on
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. With over 300 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.
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.
But First — What Is B2B Writing?
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.
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.
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.
Have you ever felt puzzled by a confusing error message, found yourself navigating 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 homeowner 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 technologies, solve issues with confidence, and make the most out of the products and processes you encounter.
In this article, you will explore the various types of technical documentation, delve into their diverse applications, and learn some essential tips for crafting your own clear and user-friendly technical guides.
What Is Technical Documentation
Technical documentation serves as the bridge between complex systems and the people who interact with them. It’s a vast umbrella term that covers any written material that explains the functionality, use, and 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: This type of 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: This type of documentation is 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: This type of documentation outlines standardized procedures for internal operations, like quality control checklists or training materials for new employees.
The quality of technical documentation can greatly affect 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.
Create an Easily Navigable Structure
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.
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.
Make Sure It’s Accessible, Jargon-Free, and Easy to Understand
Technical documentation usually consists of information that is entirely new to its target audience. In such a case, it becomes all the more important to present the information in a way that allows readers to understand it easily. Excessive use of technical jargon and complex language can make it difficult for new readers to quickly read and grasp the concepts. Simple language can also assist experienced users in quickly finding information, and your team members have to answer fewer questions from the users.
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.
Know Your Audience and Ensure the Documentation Has the Correct Level of Depth
Imagine explaining intricate financial strategies to someone unfamiliar with finance—it can be overwhelming. Similarly, in technical documentation, understanding your audience is essential. Customizing your content to your audience’s specific needs and knowledge level is crucial for creating clear and impactful documents. 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.
Include Examples, Visuals, and Interactive Elements
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.
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.
However, you must also 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. Remember, 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.
Periodically Update the Documentation
Creating technical documentation isn’t a write-it-once-and-forget-it task. The technology landscape, processes, and user expectations change quickly. To keep your documentation valuable and effective, it requires regular updates.
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. Also, 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.
Conclusion
Clear technical documentation gives your users the tools to understand your technology, solve issues with confidence, and make the most out of the products and processes they encounter.
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.
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.
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 hiring 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.
