Category: processes

Once you embark on the journey of technical writing, you will discover a few different types of articles. Tutorials, comparisons, roundups, and guides. These all serve a different purpose, and your angle will be slightly different depending on which type you are writing. When writing a technical guide, you need to make sure that you are hitting the right mark and that it makes sense to write a guide instead of a tutorial.

In this article, you will be shown what it means to write a technical guide, why you would want to do so, and you’ll be given some tips on how to make great ones.

Why Write Technical Guides?

The first question you always need to ask yourself is why. Why do you want to write technical guides? Below are a few reasons for it.

1. SEO (Search Engine Optimization)

The first reason for writing technical guides is shared among many different types of articles, and it is, of course, SEO. By writing technical guides, you have the opportunity to include specific keywords, which can be a great way of getting ranked higher on search engines like Google.

Besides using keywords, you can use guides as umbrella articles for other articles on your blog. For example, if you create a guide on how to get started with your product, you can link to specific tutorials on each subject. This will keep the reader contained within your blog and increase traffic on your site.

2. Hitting Your Target Audience

Sometimes you are lucky that your target audience quickly picks up on what you are doing, and you don’t need to explain anything to them. This, however, is not the case for most companies. Usually, you need to make your audience understand why they should listen to you.

By making high-level guides, you are introducing people to your product in an easily digestible manner. It’s uncommon that anyone would sit and read a tutorial for a product they are only considering using. It’s even more uncommon if they don’t even consider using your product. When you produce entry-level technical guides, you allow your audience to digest your product without them feeling like they are doing a deep dive into the mechanics of it all.

3. Spread Knowledge of Your Product

Of course, technical guides do not only have to be entry-level. There’s a definite value in making more complex guides, like how your product integrates with other products and concepts that are only relevant to those already working with your product. This can be very valuable, as it again introduces your audience to something in a digestible manner. Many prefer to read a well-written guide rather than sifting through documentation.

4. Let People Get Started Quicker

This last point is somewhat of a combination of the previous two. By writing technical guides, you let people get started with your product quicker than if they had to figure everything out independently. You may think, “Well, that’s why we have documentation,” and while that is correct, the documentation doesn’t serve the same purpose as guides.

Your guides should be written with a clear goal. “Getting started with X using Y.” This allows readers to find a complete overview of what they need. Documentation will usually include more technical explanations, specific implementations and is generally written much more technically than a guide. A guide leads the reader down one particular path, rather than covering many different scenarios, like documentation typically would.

Tips for Writing Great Technical Tutorials

So, you know why you want to start writing technical guides. Now you need to know the building blocks of great articles.

1. Know Your Audience

Like SEO, this is a point shared among many different types of articles, but that is only because of how important it is. Without knowing your audience, you are writing blind. In the context of content marketing, it’s the equivalent of having the dart arrow without knowing where the dartboard is.

Determining the audience helps you keep a thread throughout your article, and it helps keep you in line. If your guide is aimed at experienced developers, you can use industry terms to describe certain things. If your guide is aimed towards a general audience, you know that you need to keep industry terms to a minimum.

2. Focus on the “Why”

Many writers miss, especially when first starting, that they only explain how things are done. While this can, without a doubt, be beneficial, it doesn’t teach the reader very much. The reader might come away with an explanation of the issue at hand, but they still won’t know why they had the problem in the first place.

Maybe your guide isn’t trying to solve an issue. Perhaps it’s a guide on how to get started. In this case, you must hammer home why the reader needs to use your product. Answering the why, even if the reader hasn’t asked it, will generally always lead to a better article. Not only because there’s more substance, but because you as the writer will have to think about the subject more.

3. Having a Clear Goal

Like with the audience, you also need to set a clear goal for the guide. This will help you keep a common thread throughout the article, eventually leading to a better article. Writing a guide that jumps from point a to point c to point b can have valuable insights, but it will be a mess to read. By aligning the article with a clear goal, you can set a direction and make sure the contents are digestible.

4. Keep it High-Level

The last thing to keep in mind is that you are writing a guide and not a tutorial. Keeping it high-level doesn’t mean you can’t mention specific implementation steps or include code snippets. It means that you shouldn’t be including step-by-step instructions on how to get something working.

This is something that should be built into the goal you set. Most of the time, your goal will be something along the lines of helping the reader get introduced to a subject, more so than helping the reader get something implemented.

Conclusion

Now you know more about what it means to write a technical guide compared to writing a technical tutorial or roundup. It’s a matter of making sure the content is digestible and is open to new members of the audience you are targeting.

On top of that, you’ve got an insight into how you can build a fantastic guide, like setting a goal and focusing on the “why.”

Want to write for Draft.dev?Click here to learn more and apply today.

On the other hand, if you need help writing technical guides, or if you’d like to work with our team of writers to build content that reaches software engineers, contact us today

Most of the developer tools companies we work with generate the bulk of their traffic from two sources:

• Search engines – By targeting the right keywords, you can systematically build a content machine that generates consistent traffic, but it typically takes 6-12 months to see results.
• Social media – If you’ve built a large following of customers and fans already, you can leverage this audience to generate traffic faster but less predictably.

While the most successful companies we work with employ both strategies for each piece of content they publish, I realized that many of our clients were completely neglecting social media.

So, last month, we officially added social media collateral to our service offering. To learn more, book a call with me, or keep reading to get an overview of our service upgrade.

Social Media Marketing for Developers

I spoke to several clients over the past year about how they use social media to promote their content. While a few were effectively using it, the majority did very little to promote their content on social media.

When I dug into this, the most common objection I heard was, “We aren’t sure what will resonate with developers on social media, so we avoided it.” There are really two components to this objection, so let’s dig into this a bit more:

1. Where Do I Post This Content?

The first roadblock our clients had about promoting their blog posts and technical content on social media was that they weren’t sure where to post it.

Twitter? Our company account? Our developers’ accounts? Reddit? Facebook?

If you’ve been in marketing for long, you know that developer marketing is tricky. They have their own niche communities like Reddit, Stack Overflow, and Hacker News that are rarely used by other demographics.

Additionally, some of these communities are rather insular.

Reddit remains a bit of a mystery for most, including most corporates looking to tap into what makes stuff go ‘viral’ on this network…What you get is a potpourri of the web’s most interesting, weird and controversial content. – Business Today

Still, Reddit and Hacker News are powerful traffic generators if you know how to use them. This is where having our industry expertise can help.

2. What Should We Say?

The second problem was that many of our clients weren’t sure how to talk about the topics we cover in a way that would be authentic and resonate with software developers.

Some of our clients don’t have the technical expertise to write social media content for these topics, and even those who do rarely have time to sit down and think about five or six different social updates for each post across multiple channels.

We also find that some of the pieces we write for clients are rather difficult to write social collateral for. If you’ve never used an API to build a Slack Bot, how would you talk about this kind of tutorial on social media? What snippets are worth extracting and sharing?

Again, having subject matter experts who can guide you is the key. If your developers can do it, great, but if they don’t have time, we’re here to help.

Our Offering: Social Media Collateral for Technical Content

To solve both of the above problems, we’re now including social media collateral in our service offering.

For each article that we write, Draft.dev will provide clients with:

• Social media posts that you can schedule on your company Twitter and Linkedin accounts
• Subreddit suggestions and headlines for Reddit
• A Hacker News submission
• A detailed promotional checklist

The idea here is that your non-technical marketing associates can use these updates to help get your content out there. While making an article go viral on Hacker News is not guaranteed, you have to plant the seed if you want any shot at your content taking off.

Does Social Media Work?

We’ve already seen good results using this strategy for our own content at Draft.dev. While Google search traffic is our largest traffic driver, Twitter and Reddit rank just behind it for our developer-focused content.

The truth is that social media can work for developer marketing, but like all forms of B2D (business-to-developer) marketing, you have to know your audience and be genuinely helpful in your approach. Having great content written by subject matter experts is a start, but we’ve spent years learning how to communicate with and grow developer audiences on social media.

Learn More

Having Draft.dev’s keyword research, technical blog posts, and social media collateral is a great way to kickstart or augment your technical content marketing efforts. To learn more, book a call with us today.

When I started Draft.dev, I wanted us to consistently deliver high-quality technical content to satisfied clients around the world. Creating quality technical content requires a deep understanding of the subject matter, as well as the ability to clearly communicate complex ideas. One of the keys to creating effective technical content is to focus on the right topics and keywords that are most relevant to your audience.

Draft.dev provides SEO keyword research and topic cluster generation to our clients to ensure their target audience is engaged with our technical content. In this post, we will explore the concept of topic clusters and how we identify the right topics and keywords for our clients’ technical content. If you have questions, feel free to book a call with me.

What Are “Topic Clusters”?

First, if you’re not an SEO expert, you might not be familiar with the term. A “topic cluster” is a method for intentionally building content designed to rank well in search engines (especially Google).

The idea is that by writing several pieces of content that are related, you can develop a really valuable “pillar piece” supported by a handful of “supporting pieces.” By targeting keywords that have relatively low keyword difficulty and decent volume, you can ensure that some of your supporting pieces rank on the first page of search results quickly.

Then, by linking from those highly-ranked supporting pieces to the more difficult-to-rank pillar piece, you increase its rank as well. The goal is to eventually start ranking highly valuable, high search volume pillar pieces on the first page of Google results.

In this post, I’ll walk you through how we do this at Draft.dev so you can try this for yourself or better understand what you’ll get when you work with us. I’ve also recorded a video version so you can follow along with a real example if you’d like.

Finding Keywords

Writing blog posts that are likely to rank well in Google is a complex process that I won’t dive into here, but I will say that the process always starts with picking the right topics to write about.

The first thing we do is sit down with each client to build a list of ideal keywords. We ask a few questions that usually lead us to uncover lots of areas for exploration, including:

• What would be your dream keywords to rank #1 for? These should be 1-2 word, industry descriptions like “continuous integration,” “automated testing,” or “python IDE.”
• What work are engineers doing when they decide to use your product? What problems might they encounter leading up to that decision?
• What tools would an engineer use alongside your product? Are there specific languages or frameworks they need to use?
• What long-tail searches would you like to rank highly for? (e.g., “how to automate GitHub backups” or “how to pick the right database”)
• Who are some of your direct competitors?

After this planning session, we usually have a list of 10-50 keywords. We then take this list and start exploring. Using tools like ahrefs, Google Keyword Planner, and industry research tools, we then generate thousands of keywords to explore in more detail.

This is where the science and art of keyword research come in.

Ahrefs will give us estimated monthly search volume and difficulty, but it doesn’t necessarily tell us the user’s search intent or how relevant each keyword is for our client. For that, we use our industry knowledge, competitor research, and past experience to cull the list down to a few hundred relevant, rankable keywords.

Planning Clusters

After building this list of relevant keywords that are not overly saturated, we start to comb through them manually, grouping similar ideas and terms into groups. Again, this is part art and part science because you have to understand a lot of industry jargon to do this well.

This is also where specializing in content for software developers gives us a huge leg up on general-purpose SEO consultants. The topic clusters we build are based on a deep understanding of how software engineers and engineering leaders use the internet to solve problems on a daily basis.

Usually, we can build 2-3 topic clusters with a pillar piece and 4-6 supporting pieces in a single round. If we can’t, we go back to the previous step and brainstorm more keywords to find another unexplored niche.

The Final Result

At the end of this process, we supply clients with a simple, easy-to-understand map of our results in a spreadsheet. We’ll review each article with our client and make sure they align with the client’s product and strategy before creating detailed content briefs and outlines.

Sometimes this requires a couple of iterations, but it’s usually a quick process, about one week within our client onboarding timeline.

Once we’ve agreed on topics, briefs, and content types, we’ll start production. With 300+ technical writers in our pool, we can cover almost any software development topic, and we’re always willing to recruit specialists when the project calls for it.

Are Draft.dev’s Topic Clusters Right for You?

Using keyword-based topic clusters like this isn’t suitable in every situation. For example, if you’re hoping to create content as sales collateral, helping your sales team move prospects down the funnel, you might not care so much about search volume or ranking in Google. Similarly, if you’re primarily interested in content that will resonate on social media, we provide community research to create a content plan for our clients.

On the other hand, if you’re hoping to build awareness, generate new leads, or build up your domain authority to make ranking for more difficult topics easier in the future, this strategy is a perfect fit.

By focusing on keywords you can rank for within a few weeks, you won’t have to wait years to see a return on investment for your content. You can attract buyers at the top and middle of your funnel to raise awareness and introduce your solution. Then, by retargeting them with ads or introducing them to your mailing list, you can build a content engine that delivers consistent growth for years to come.

To learn more, ask questions, or get started, book a call with me today

With a growing number of writers around the world and a growing roster of clients who rely on us for top-notch technical content, one of the challenges we face is making sure each assignment gets matched to the best technical writer possible. In this blog post, I’ll outline our approach, which we share with writers and clients when they ask about this topic.

About Our Writers

First, if you’re not familiar with Draft.dev, we write technical content (tutorials, guides, comparisons, etc.) aimed at software engineers, data engineers, and technology leaders. Because our content is so technical, we don’t work with typical freelance writers – almost all our writers are practicing software engineers or managers.

Since almost all of our writers have a day job, their capacity is limited. Most contribute 1-2 articles per month, so while some are matched up to the same client consistently for an extended period, many work with several clients per year. This means that we spend a fair bit of time finding the best writer for each article we commit to.

Our Process

Our writers are busy professionals, so we give them as much autonomy as possible regarding the topics they want to write and when they want to write them. On the other hand, we want to make our clients happy and produce outstanding content for them on a predetermined schedule.

So, our process works like this:

1. Weekly Email to Writers

Each week, we send an email to our writers with all the topics we currently need a writer for. We work with clients to determine these topics when they sign on with us, so while writers don’t typically get to “pitch” topics, they have no obligation to take on a topic they don’t know well.

PS: If you’d like to apply to write for Draft.dev, here’s the application form.

2. Gathering Replies

Next, we wait a few days for our writers to read and reply to the email. Then, we create a list of writers who replied and which topics they are interested in. Some writers prefer to work exclusively on topics they already know well, while others take writing as an opportunity to learn new things. Either approach is fine so long as they are realistic about their ability to write on the topic with authority.

3. Matching Writers to Articles

This is where it gets a little fuzzy, and I’ll admit, sometimes challenging. Our goal is to fairly spread assignments out to our writers while ensuring that each writer has the skills to complete the article.

So here’s what we look at:

1. Proven knowledge of the topic – We look at each writer’s past work with us, their writing samples, and their work experience on Linkedin or GitHub to see if they have the technical skills needed for this article.
2. Proven ability for this type of writing – Writing a tutorial is very different from writing a good technical roundup, and that’s very different from a high-level guide.
3. The writer’s current work queue – We rarely give writers more than one assignment at a time because we don’t want to overwhelm them. Most articles require some revisions, so we don’t want writers to overcommit and be unable to handle revision requests promptly.
4. Is this a new writer? – We only accept a few applicants every month, but we try to give new writers a chance to prove themselves within their first few weeks. At the same time, we don’t want to give them an assignment that is out of their depth, so we may reserve some “easier” pieces for new applicants.
5. When was their last article? – As I mentioned above, we try to spread the work around, so if a writer hasn’t gotten an article in a month or two, we might give them a slight priority over a writer who’s just had a couple of pieces recently. This helps everyone get a fair shot and helps us maintain a diverse writer pool.
6. Speed to respond – Finally, if a writer takes 3 or 4 days to respond to our weekly email, it’s likely many of the pieces will already have been matched off.

4. Handling Unmatched Assignments

If, at the end of the matching process, we couldn’t find an interested writer for a particular article, we have a couple of options.

First, we might look through our list of writers and reach out to any with the requisite skills. Maybe they’re interested but can’t start this week? Or perhaps they missed the email? We usually build enough flexibility into our deadlines to accommodate small adjustments for the right writer.

Second, we actively recruit writers with specific skills. Typically, when a new client signs on, we’ll look at our existing writers and any who have applied to make sure we have enough people on board to handle the new work. But, some topics are just hard to find qualified writers for, so we spend time every week actively reaching out to engineers outside our network who might have the skills to write these hard-to-match pieces.

While this process is likely to change as we grow, our philosophy is likely to remain the same. We want to provide engineers with great opportunities to showcase their expertise while giving our clients the best technical content possible.

What Can Our Writers Who Want More Work Do?

Sometimes writers ask me what they can do if they want more writing work with Draft.dev. While all our writers today are independent contractors and we can’t guarantee a specific number of articles, here’s what I tell them:

Do Your Best on Every Article

Delivering your work on time, consistently, and at high quality is the #1 thing writers can do to improve their chances of getting more work. Writers who follow our style guide, self-edit, follow the outlines and briefs, return assignments on time, and respond to revisions promptly will almost always get more assignments in the future.

Conversely, if you agree to write an article about a topic you don’t know, and it goes poorly, you may not be considered for future work at all. When issues come up, or you realize an article is out of your depth, let us know as soon as possible so we can find another author.

Be Flexible

If you want more work and you’re willing to learn some new skills or research a complex topic, let us know. While some articles require previous experience, we give writers a shot at new topics if they’ve proven they can do good work on well-known concepts in the past.

More Articles are Just a Week Away

Finally, we have new topics prepared every week. As they come in, we continue to send out emails to writers, so some weeks might have many options, and others might not. Just keep an eye on your inbox!

Interested in writing for Draft.dev? Click here to learn more and apply today.

Want access to our fantastic pool of writers? Schedule a call to learn more about what we do.

As your blog grows and you get more writers to contribute, you need to build documents and processes to help you maintain high quality and consistent style. To serve this goal, you should create a style guide to help writers and editors stay on the same page.

Generally, a style guide includes expectations for your contributors. Depending on your priorities, you may include more or less information than we do at Draft.dev, but our style guide should give you an excellent place to start. We send this style guide to all new contributors to ensure they are familiar with our expectations, and we refer to this guide throughout the editing process.

Of course, ours is not the only example of a technical writing style guide. If you’re looking to compare your options, check out Google’s developer documentation style guide, DigitalOcean’s technical writing guidelines, and some of the other guides here. If you’re creating a style guide, I’d recommend reading over several and deciding what you want to include in yours.

The Draft.dev Technical Blogging Style Guide

At Draft.dev, we specialize in creating technical blog content for companies that want to reach software engineers. While most of our writers are software engineers first and authors second, we still expect them to follow consistent standards for each of our clients.

Below is our style guide, which is broken up into four sections:

1. Voice
2. Content
3. Conventions
4. Communication

Voice

Write in Second Person

Speak to your readers directly using “you” and “your.” Avoid “we” and “our.”

Good:

You can use a web browser (like Chrome, Safari, or Edge) to access web sites on the internet.

Bad:

We can use our web browsers (like Chrome, Safari, or Edge) to access web sites on the internet.

Use Conversational, Business-Appropriate Language

Read your article out loud and ask yourself, “Would I talk like this at work?” Use your real-world experience, but avoid jargon when possible.

Good:

Experts agree that the internet was not the product of any individual mind, but a series of advances in networking and computer science.

Bad:

Many scholars would agree that, had it not been for active networks, the simulation of Lamport clocks might never have occurred. The notion that end-users synchronize with the investigation of Markov models is rarely outdated. A theoretical grand challenge in theory is the important unification of virtual machines and real-time theory. To what extent can web browsers be constructed to achieve this purpose?

Don’t Repeat Yourself

Eliminate wordiness. You shouldn’t repeat yourself when programming, and you shouldn’t repeat yourself when writing.

Good:

A lively debate rages among software developers. The contentious issue is: tabs or spaces?

Bad:

There is currently a lively, ongoing controversy among many computer scientists and other professional in the field of software development: theories are being spun and arguments are being conducted among them about whether the use of tabs to designate indentation in a document is superior to the use of spaces for the same purpose.

Avoid Gatekeeping

Write for an international audience of developers from a wide range of backgrounds, races, ethnicities, cultures, and experience levels. To that end, avoid language that is exclusionary or encourages “gatekeeping.”

Good:

Fork the main branch and make the appropriate changes.

Bad:

Obviously, you simply fork the master branch before making the appropriate changes.

Use the OpenGates Checklist here to ensure you’re not writing in a way that excludes others.

Content

The Introduction

Every article should have a 1-3 paragraph introduction. A good intro needs to answer a few questions right away:

• What’s the pain point I’m addressing here? How do I hook my readers? 
• What’s the solution to this problem?
• What am I going to do in this article?

Make sure your introduction is completed by letting the user know how you’re going to teach them to solve this pain point.

Support Claims With Evidence

For every claim you make, ask yourself, “How can I prove this?” You can do this by:

• Including a link to a reputable article
• Including a quote from another source
• Citing an academic study
• Linking to the official documentation
• Interviewing knowledgeable professionals

Good:

While [Postgres can handle hundreds of columns](https://nerderati.com/2017/01/03/postgresql-tables-can-have-at-most-1600-columns/), it might not be a good idea to take advantage of this feature.

Bad:

While I’m guessing Postgres can handle a lot of columns, it might not be a good idea to use more than a hundred if you can help it.

Plagiarism and Copyright Infringement

Written content that is copied directly from another source must be quoted and cited appropriately. Switching out a few words in a sentence is not enough to make the content original, so be sure to put everything in your own words.

Bad:

I’ve always thought that measuring programming progress by lines of code is akin to measuring aircraft building progress by measuring weight.

Good:

“Measuring programming progress by lines of code is like measuring aircraft building progress by weight.” – Bill Gates

The bar for using images is even higher. You may not use images from another website unless they expressly allow it. If you need stock images, use a site like Unsplash or one of the options here.

The Conclusion

Every article should include a 1-2 paragraph conclusion. This should restate the thesis of the article and remind readers what they learned. It may also include other resources readers can reference to learn more.

Good:

While JSON data types come with some drawbacks, they are useful when you need more flexibility in your data structure. Thanks to Django’s native support for `jsonb`, you can get started using JSON data in your web applications without [learning all the native Postgres query operators](https://www.postgresql.org/docs/current/functions-json.html).

Next time you need more flexibility in your data model and want to benefit from the strengths of Postgres give `jsonb` fields a try.

Conventions

Write in Markdown

All articles should be written in Markdown and submitted in the Google Doc sent to you when you accept the assignment.

Good:

Markdown is a formatting language often *used by static site generators* and *blogs*. If you aren’t familiar with its syntax, you can [click here to learn more](https://guides.github.com/features/mastering-markdown/).

Include Unmarked and Annotated Screenshots

If you need to circle something or add some text to a screenshot, please provide a screenshot annotated to the best of your ability, as well as an unmarked copy of the screenshot. This empowers our clients to redesign them according to their own branding if desired.

If you don’t already have a preference, we suggest using any of the following tools:

• dbdiagram.io
• Excalidraw
• Google Drawings
• Mermaid-JS
• Lucidchart

These are also all great options for any rough architectural diagrams you may need to make.

Upload Images to Imgur

If you have screenshots or diagrams in your article, upload them to Imgur’s free image hosting service and embed them using Markdown. Include descriptive text inside the brackets ([...]) so that screen readers can describe the image.

Good:


Bad:


Use Headers to Break Up Sections

Headers make your content more scannable. Use ##, ###, and #### header tags to denote different sections. Headings should be written in title case.

Good:

## How to Use JSON Fields in Your Python Application

…

### The Two JSON Formats Supported by Postgres

…

Bad (not title case):

## How to use JSON fields in your Python application

…

The two JSON formats supported by Postgres

…

Denote Code with Backticks

Use code blocks when the code is one or more lines long or deserves special emphasis.

Good:

“`

function snafu() {

return null;

}

“`

Bad:

`function snafu() {

return null;

}`

Use inline code when referring to a variable name or short command in context.

Good:

Call the `snafu()` method to exit and return to your command line.

Bad:

Call the “snafu()” method to exit and return to your command line.

Use Double Quotes for Quotations

Use blockquotes when the quote is two or more lines long.

Good:

Some text leading up to the quote.

> “The field/element/path extraction operators return NULL, rather than failing, if the JSON input does not have the right structure to match the request; for example if no such key or array element exists.”

Some text after the quote.

Bad:

Some text leading up to the quote. “The field/element/path extraction operators return NULL, rather than failing, if the JSON input does not have the right structure to match the request; for example if no such key or array element exists.” Some text after the quote.

Use inline quotes when the quote is relatively short or when you’re referencing a single word or phrase.

Good:

“There’s nothing to see here,” said Davies.

Bad:

> “There’s nothing to see here.” – Davies

Use Emphasis Sparingly

Use italics to emphasize text or use bold to suggest strong emphasis.

Good:

There is *nothing* as important as using **spaces** to indent your code.

Communication

Communicate Delays and Roadblocks to Your Editor Proactively

You will not be penalized for late work if you’ve been in communication with us about the assignment. We can offer technical help and extensions, but you must ask two or more days before the due date.

Good:

Hey Karl,

I know the Postgres article is due next week, but I’m running into trouble. Would you be willing to hop on a quick call and explain the JSON fields in Postgres? Or do you have any resources that might help me out?

Bad:

Hey Karl,

I know my Postgres article was due today, but I’m not able to figure out the JSON fields in Postgres. Could I have an extension until next week to struggle with it more?

Authors that miss deadlines without communicating will not be eligible for future assignments.

Check Your Email When You Have an Open Assignment

While you have an open assignment, you should respond to emails within 48 hours unless you’ve notified us of your unavailability. If the assignment is overdue, you should respond within 24 hours.

Good:

Hey Karl,

Thanks for the update on this article. I’ll keep that in mind while I’m working on the piece this weekend.

Bad:

Hey Karl,

Sorry, but I didn’t see your email until today and I know the article is due now. I’ll try to incorporate your feedback before midnight if I can.

Authors that fail to respond to emails about open assignments will not be eligible for future assignments.

Final Notes

Creating high-quality technical content requires consistency and clear expectations. While having a style guide may not be necessary during your blog’s early days, it’s an invaluable asset as you grow.

Now that you’ve seen our style guide, I’d love to hear from you. If you have questions about an article you’re writing, email karl@draft.dev for help. If you’d like to talk about creating content for your blog, you can schedule a call with me here.

Hiring is always hard, but the more specialized your hire is, the harder it will be to fulfill. If you’re managing a technical blog and you want to stop writing everything yourself, you’ll need to recruit and hire technical writers to help you out.

While traditionally used in education, rubrics are a fantastic tool for hiring, and I’ve used them for years both as an engineering manager and content manager at Draft. Whether you are bringing on a part-time freelancer or a full-time hire, having a good rubric for content will help you objectively evaluate candidates and keep you focused on the criteria that matter for your job.

What is a Technical Hiring Rubric?

A technical hiring rubric is a document that defines the criteria you use to decide whether a candidate is a good fit for your role or not. It typically includes several attributes upon which you will evaluate candidates and a few levels within each attribute that measure their skill.

How are Rubrics Most Helpful to Writers?

Rubrics let writers gain a better understanding of what you’re looking for in a hire. Providing your writing process rubric up-front allows writers to become intimately familiar with your expectations and needs – encouraging them to rise to the challenge. In some cases, writers may even self-screen themselves, which gives you the greatest amount of qualification during the hiring process.

To effectively use a rubric, you need to apply it consistently using measurable and observable behaviors. This means that a good rubric eliminates hiring by “gut feel” and forces you to stay focused on the characteristics that candidates display throughout the hiring process.

The Draft.dev Technical Writing Rubric

As I started hiring more writers for Draft.dev, I began refining a rubric that would allow me to evaluate them quickly and objectively. Today, I’m sharing this rubric with you so you can use it as a starting point for creating your own hiring rubric.

Our rubric currently has ten attributes that fall within three broad categories. Each of these attributes has 3-4 levels we can use to compare writers. We use this rubric to decide which candidates to bring on during the hiring process and as an ongoing evaluation tool for our existing writers. This strategy helps us consistently provide high-quality technical work for our clients.

You can get a copy of the rubric here or read on for an explanation of how we evaluate writers using this rubric.

How to Write a Rubric

Rubrics are designed to make life easier (and far more efficient). At Draft.dev, we believe in cutting the guesswork right from the get-go with blueprints designed for accessibility and success. Here’s how to write a rubric for writers based on our starting template.

Category 1: Writing

Writing skills are necessary for the kind of work we do at Draft.dev, but defining what it means to be a “good” writer is surprisingly hard. Many people use the, “I know it when I see it” test, but I’ve found that insufficient. There are three attributes I look for in strong writers.

Conventions

Grammar and spelling errors can be overcome. With tools like Grammarly, we can edit a writer with decent conventions, but submitting samples full of mistakes points to a problem with attention to detail. Every writer makes mistakes, but that doesn’t forgive sloppiness.

Writers who have mastered conventions will submit error-free work and may even spot mistakes in others’ work during the application process.

Language

English is a tough language to master. As such, many non-native writers will struggle to word things in a way that native readers find natural. For example, the phrase, “Let me explain you the reasons I believe this to be true,” is missing a preposition and somewhat strangely worded. It’s not glaringly incorrect, but it shows a deficiency in language that is common among inexperienced writers.

Writers who have strong language skills use engaging words, varied sentence structure, and stylistically sophisticated vocabulary that isn’t overly wordy. It’s tough to do.

Organization

Finally, great writers have to be great organizers. While having good content briefs with outlines can help with higher-level structure, the writer will still have to decide how to present sequential information in a way that readers can grok.

To reach the highest level in this attribute, writers must create clear transitions between topics and consistent focus throughout the entire sample piece.

Category 2: Technical

As a technical content agency, Draft.dev’s writers must have specialized experience. While not every piece we produce requires deep knowledge about a specific technical topic, writers must research, understand, and speak to technical topics.

Development

In this context, “development” doesn’t mean software development skills – it means the ability to develop and present an idea. A well-developed piece of writing goes beyond the step-by-step “how” and builds the “why” as well.

A writer who can present their main idea and strongly support it with technical evidence while keeping the “why” central to the work will get full points in this category.

Depth

Technical depth describes the writer’s ability to go beyond entry-level writing on the topic at hand. Regurgitation of the “getting started” walkthrough is not that useful for the writing we do with our clients. Writers need to show that they understand the underlying technical justification for their decisions.

Writers who display depth of knowledge usually have years of real-world experience and knowledge of the technology’s inner-workings.

Demand

Technical knowledge is spiky. A writer may know a lot about Rust, but nothing about Python, so while they can display depth by diving into the Rust compiler, if none of our clients need Rust writers, their skills aren’t in demand right now. While technical writers usually have two or three areas where they can contribute, their skills have to match up with our clients’ needs to be a good fit.

Writers with unique combinations of skills or experience that happens to match our clients’ technology stack will do the best in this category.

Correctness

Finally, writers must be technically correct. This is usually linked closely to depth – if a writer can’t go deep on a topic, they are less likely to get the details right – but not always. For example, a writer might create some sample code that doesn’t work even though their explanations are on-point.

Writers will get the most credit in this category when they have no factual errors, and all their assumptions are backed up with evidence or experience.

Category 3: Work

The last category is work habits. Even great writers who are technically qualified may be a bad fit for Draft.dev if they’re not consistent team players. Each of our writers works remotely as an independent contractor, so their ability to communicate, respond positively to feedback, and work independently are important to their success.

Communication

While writing skills are evaluated in the first category, our writers must also be responsive, prompt communicators. With clients and writers around the world, we don’t have set “working hours,” but we require writers to respond to emails and requests for revisions within a reasonable amount of time.

The best writers proactively notify their editor with questions or delays as early as possible and communicate their progress along the way.

Attitude

As a writer, you have to be able to handle feedback – both positive and negative. Edits aren’t a personal attack, so we look for writers who actively seek out feedback. Great writers at Draft.dev enjoy the guidance we offer rather than seeing it as a burden.

Independence

Finally, our technical writers have to be able to solve problems independently. This doesn’t mean they can’t ask questions – they should reach out proactively when stuck – but they should start projects early in case anything comes up.

We Can Help You Create Great Technical Blog Content

I hope our rubric helps you hire better technical writers, but I also hope it shows you how tough finding great writers can be. If you’re not sure about hiring your own writers, we might be able to help. At Draft.dev, we write technical content for software engineering blogs using our pool of highly skilled technical writers. We also offer content planning and editing services.

If you’d like to learn more, send me an email or read about our process at Draft.dev.

Technical Writing Rubric FAQ

What is a writing rubric?

A writing rubric is a set of instructions that outline all responsibilities and expectations for a writer. It may include skills, language use, attitudes, and other detailed attributes of a potential hire. Writing rubrics are typically filled out or managed by heads of content, and are used to measure skill or evaluate in writing.

In which way is a rubric most helpful to writers?

Rubrics give writers the greatest amount of context for their work. A specific rubric for content provides context, gives direction, and allows writers to understand expectations before taking on a role or filling a position. This ensures that projects are completed to exact specifications (and to the satisfaction of both parties).

As a writer, when should you look at the rubric that will be used to evaluate your writing?

Writers should constantly refer to a writing rubric while working on their projects. If one is not provided, it’s highly suggested that you create your own rubric instead. Read through what is expected of you before beginning the writing process, and be sure to tag all interested parties with any questions you may have.

There are two mistakes that most companies make when they decide to pursue technical content marketing:

1. They don’t have a content plan.
2. They don’t know how they’re going to distribute their content.

I recently wrote about how I recommend starting with a checklist to promote your blog posts. While I could say more, I’m going to focus on the first problem: creating a technical content plan.

What is a Content Plan?

Most companies that start a blog have a higher-level strategy. They know why they want to start creating content but rarely dive into the specific article ideas and resources they want to create.

A content plan is a detailed outline of the content you want to produce for your blog.

If you’re building a technical blog aimed at developers, tailor your content plan to fit (1) your audience, (2) your product/service, and (3) your available writing resources.

I’ll add more about how you can create a content plan later, but let’s start by looking at an example:

Here’s the sample content plan I share with my clients at Draft.

Let’s take a look at the first article in the content plan: How to Deploy WordPress to a Kubernetes Cluster.

The Title

While it may change, the working title tells us what each article’s main keywords are and the tone. Articles that start with “How to…” like this one are generally tutorials, but as you’ll see, we clarify that further down in the plan.

The Pitch

Freelance journalists typically write a “pitch” to sell an editor on their idea. The pitch in your content plan accomplishes a similar goal, giving others a high-level view of the article what readers will learn.

Assets Delivered

I like to be clear about what will be entailed in creating each piece of content I write. Include expectations for the article length, type, and supporting data or code samples that will be delivered.

Audience

If your writer assumes the article is directed at entry-level developers, but you meant it to be aimed at managers, you’re not going to be happy with the outcome. Having a clear audience attached to each piece will also help you think about how you’ll promote it after publication.

Outline

Finally, your content plan should include a brief outline. You can let the writer fill in details or adjust it as necessary, but having some detail shows that you’ve thought about the topic and know what it will entail before you pass it off to a writer. If you’re the writer, you really need an outline.

Why Do You Need a Content Plan?

You might think that creating a content plan with detailed pitches and brief outlines for each of your articles will be a considerable time investment…and you’d be right.

The truth is that if you don’t create a plan, your writing will suffer. You’ll get different levels of quality from various writers, you’ll have to return more work for a rewrite, and you won’t be able to let other stakeholders see what your team is working on.

Before I start working with a new client, I create a content plan for the first 3-6 months of our engagement. Having it is a massive benefit for both my clients and me, so while it’s an investment, it’s well worth making.

Here are just a few of the reasons you should create a content plan:

Aligns Content and Strategy

It’s easy to fall into the trap of publishing anything anyone wants to write on the blog. An unfocused approach like this might occasionally result in a home run, but most of your posts will add very little value. By explicitly defining each piece of content you want to create, you can make sure your posts serve your overarching strategy.

Helps Drive the Plan for Promotion

Having a defined audience for each post you write will help your marketing team decide on a promotional plan for each piece. That allows them to do research before the post goes live to give it the best chance of success the moment it’s published.

Enables You to Find the Right Writers

Whether you’ve got dedicated in-house resources or a large pool of community contributors, writers will struggle to come up with good topics consistently. By having a list of content ideas, you can control the content’s quality and topic choice. You can even start targeted outreach to find writers with specific experience for each post.

Minimizes Back-and-Forth

One of the most frustrating things as a writer is having unclear expectations for your work. Imagine spending 5-10 hours writing an in-depth, technical piece and then being told you missed the mark. I’ve done it; it sucks. A content plan will make sure writers don’t waste their time or yours.

How to Create a Content Plan

Once your team agrees that a content plan is necessary, it’s time to get to work. There are three phases to coming up with a content plan:

1. Defining the content strategy
2. Coming up with ideas
3. Research and add details

Generally, step 1 is done at the top. Whether it’s the Head of Marketing, Community Manager, or Content Marketing Manager, someone familiar with the company’s overarching goals should be responsible for choosing and defining a content strategy. This strategy won’t go into specific article ideas, but rather set the target audience, the kind of content you’ll create, and how you’ll capture readers to turn them into leads.

Next, use the strategy to come up with a list of possible article ideas. At this stage, each idea will probably just be a title and maybe a couple of bullet points. If there are lots of ideas, you may need to rank them and pick the winners. If you’re having trouble coming up with ideas, you might want to take a break and return to it later.

Finally, someone on the team needs to be responsible for researching each idea and adding details like the outline, pitch, and assets. After these details are added, the team should review and approve them before doling them out to writers.

Having Trouble?

If all that seems overwhelming, and you’re tempted to skip the content planning phase, you don’t have to go in alone. At Draft, we help software engineering blogs define and carry out content plans.

If you’re interested, send me an email or learn more at Draft.dev.