Category: processes

Draft.dev creates technical content for dozens of developer tools companies , so process optimization is critical for our success. But process optimization isn’t just about being more efficient. It also helps us deliver consistently high-quality content to our clients, and allows us to bring on new clients more quickly.

Defining what content type a specific article will be—and what deliverables clients can expect to receive as a result—is a key component of this process.

In this article, I’ll break down some of the types of technical content and deliverables we currently offer at Draft.dev and why we use them.

Content Types

Different articles fall into different content types, and these content types determine how we produce each article.

If an article is supposed to be a tutorial, it will include clear, step-by-step instructions for the reader. If the reader can replicate what was done purely from the provided instructions, this article has done its job.

This article by Draft.dev author, Lucien Chemaly is a good example of a tutorial.

On the other hand, articles that are meant to introduce a concept to the reader (rather than provide instructions), are considered “guides.” These might be high-level overviews of a technology or collections of best practices for specific types of work.

This article on technical documentation best practices by our writer, James Walker, is a good example of a guide.

Knowing what type of content each piece is meant to be helps the writer understand the goals of the piece, and it helps us set accurate client expectations. You can read more about the specific content types we use on our Content Types page.

Deliverables

While content types help set the overall article tone and structure, the deliverables define the actual pieces of work that come with the article.

We currently offer one or more of the following options when defining content deliverables:

• Screenshots
• Stock images
• Rough architecture diagrams
• Code samples
• Demo application in a GitHub repository

Typically, articles will use 2-3 of these deliverables. For example, tutorials often include screenshots and code samples, while guides might have an architecture diagram and a stock image. It’s all about efficiently communicating what should be included.

Let’s break down some specific content deliverables.

Screenshots

Screenshots shine when text can’t explain what’s going on, or when a text-based explanation would be too complicated to read. If you’re comparing five different performance testing tools for an article, screenshots would help the reader to distinguish different sections.

Imagine you’re writing a tutorial where you’re teaching the reader to place four buttons in a grid on the screen. You could just include code samples since if the reader copies that code they’ll get the desired result. But oftentimes readers aren’t just copying and pasting your code—they’ll write it themselves as a way of training muscle memory. Including a screenshot of how the buttons should look will let the reader verify if they’re correct.

Stock Images

It doesn’t always make sense to have a screenshot or code samples in an article. This is typically the case for guides or persuasive writing pieces. However, an article without any images or illustrations can sometimes become tedious to read. If that’s the case, we’ll ask for a stock image to be included to hook the reader from the beginning.

Rough Architecture Diagrams

Writing about some topics can get complicated—fast. This complexity can quickly become too much for the reader, so rough architecture diagrams are extremely useful.

As you probably noticed, we specified rough diagram. While our talented writers are excellent engineers, they’re typically not illustrators—at least not professionally. If you do want a professionally illustrated diagram included, we can provide that. Reach out to learn more.

Code Samples

We sometimes ask our writers for code samples. This is common for tutorials where the writer provides step-by-step instructions. In this case, explaining a concept isn’t usually sufficient—we want concrete examples of how something should be written so the reader can replicate it.

Demo Application

In cases where there is substantial code included in an article, we will ask our writers to create a well-organized public Github repository to house the project files involved. Clients can then fork or transfer the repo to their internal team if they’d like to maintain the project.

Why are Content Types and Deliverables Important?

Content types and deliverables significantly help define our expectations for both our writers and clients. Adopting these standard options has allowed us to more consistently deliver quality content without sacrificing speed of delivery.

To learn more about working with us at Draft.dev, schedule a discovery call by clicking here.

If you’re curious what a completed Draft.dev article might look like, here you have it. This article serves as a visual demonstration of our house style (eg, our default formatting for text, code snippets, and images, as well as a peek into our copy editing standards).

What’s actually written in the text of this visual guide doesn’t particularly matter, but Lorem Ipsum is boring. So if anyone’s interested in why Draft.dev’s style guide is the way it is, they’ll find some insight here.

You can find the in-depth style guide used by our editorial team here, if you’re curious and want to see just how deep our attention to detail goes.

Why Markdown?

For starters, all of our articles are Google Docs written in Markdown. This ensures a couple of key functions:

• Our clients don’t have to learn new tooling. The Google suite is familiar throughout the business world, from developers to marketers. So no matter who is handling a client’s content, they’ll most likely be able to easily work with a Google Doc.
• Markdown formatting is universal. No matter the client’s content management system, their text editor will know exactly what to do with Markdown. Providing our articles in Markdown ensures that no unexpected formatting ends up in the client’s published content—no matter where they publish it. Any branded fonts and colors and spacing will lay out exactly as the client expects them to.

Want to see what the Markdown looks like before you put it in your CMS? Check out a Markdown editor like Dillinger for a preview.

Why Is Draft.dev’s Style the Way It Is?

To ensure consistency for all our clients, we’ve built a robust style guide for our editorial team to follow. Our style includes standards from a few common style sources, generally in this order:

1. House style. These are standards that our editorial team has decided on in-house. If our editorial team is unsure how to resolve an edit, they check this guide first.
2. Chicago Manual of Style. A common standard for long-form writing, the CMoS sets down rules for everything from formatting to comma use.
3. Merriam-Webster. The online collegiate edition is our go-to for spelling.

Note that Draft.dev uses American-English spelling and punctuation.

Headers Are Title Case

If a client’s content marketing has decided on any style standards, chances are they’ve made a decision as to how they want headers to look. Headers are typically a short phrase in a larger/more distinctive font to add structure and context to paragraphs within long-form content.

Draft.dev uses title case for headers of all hierarchy; that means most words (but not all; CMoS is very stern about this, sorry about that) in a header are capitalized.

If our clients prefer sentence-case headers (ie, only the first word is capitalized), we can accommodate that too!

Code Snippet Formatting Is Kept Simple

While short lines of code can be kept in-line (eg, <ButtonText>) with the rest of a paragraph, larger blocks of code stand on their own, like this:

<Buttons>
    <Button guid="guidOktaAuthVsixPackageCmdSet" id="MainToolWindowCommandId" priority="0x0100" type="Button">
        <Parent guid="guidSHLMainMenu" id="IDG_VS_WNDO_OTRWNDWS1"/>
        <Icon guid="guidImages" id="bmpPic1" />
        <Strings>
          <ButtonText>Okta Extension</ButtonText>
        </Strings>
    </Button>
</Buttons>

To ensure language-specific syntax highlighting for the code block, a client’s content management system will most likely require a plugin.

Conclusion

Draft.dev’s house style promises consistency and standard elegance through a highly detailed set of standards established by a team of experienced editors. However, if a client requires the use of their own style standards we can tailor our services to your style guide too!

Documentation quality can make or break developer tools. Good docs are essential so devs can learn how tools work and which use cases they apply to. Content should be detailed, accurate, and accessible, clearly explaining concepts without making readers spend time hunting for additional information.

This article shares some best practices for creating and publishing developer-oriented documentation. These pointers will ensure your guides, tutorials, API references, and other resources all create a positive experience for devs using your tool.

Why Developer Tools Need Good Docs

Developers use software documentation in two main ways: first, to evaluate the high-level capabilities of your tool and, second, to learn the technical details of how it’s used and integrated. Even the best tools are useless if developers don’t know what the tool does or how it achieves its purpose, so it’s vital to invest in authoring quality documentation that makes dev life easier.

The effects of bad documentation—whether missing, outdated, or hard to find—shouldn’t be underestimated. Documentation issues create developer roadblocks that cause frustration and can lead to tools abandonment. Poor docs also drain your internal resources as support teams field more inquiries from uncertain devs seeking answers.

Best Practices for Great Documentation

Creating effective documentation starts with following standard best practices for communicating information:

• Write clearly and concisely, avoiding ambiguous terms and jargon.
• Adopt or create a style guide to ensure a consistent tone applies across your documentation.
• Ensure your docs entry point is easy to find, such as a link from your website or README file.
• Review your docs and replace any outdated information regularly. (If there’s anything more frustrating to developers than missing docs, it’s docs that prove to be incorrect.)

Beyond these principles of documentation, here are four key features to focus on when you’re writing for developers.

Go In-Depth into Features and Use Cases

Your documentation should be a comprehensive, one-stop place to find any answers that developers require. It’s important to provide in-depth details about all the features provided by your tool in addition to the ways in which they can be used.

Beyond a description of the what and how of your tool, your docs should also clearly explain the why. Detailing your target use cases with the ways in which your tool achieves them and the reasons behind any opinionated behavior enables devs and buyers to easily understand the problems you’re trying to solve.

The exact content to cover depends on the type of tool you’re creating. APIs need a breakdown of every endpoint, the parameters they accept, and the responses they issue, for example, while CLI apps should include a reference for each supported command with its options and how they can be combined.

Such detailed reference material ensures developers can easily discover available functions and learn how to use them. The npm documentation provides clear instructions for every command, for example, offering a clear technical synopsis, a description of the command’s use case, and a list of supported configuration parameters:

Create High-Level Summaries to Help Devs Familiarize Themselves with Your Tool

Technical depth mustn’t replace high-level guides and overviews, however. Introductory tutorials that are relatively light on detail but walk users through common workflows in simple steps should also be provided. In particular, create concise installation or setup guides for all supported platforms and environments to ensure that first encounters with your tool are frictionless.

This kind of content lowers the learning curve for first-time users who aren’t yet ready to head deep into your reference material. The GitHub REST API showcases how both these content types can be presented—the top of the sidebar is dedicated to quick-start guides and explanations of key concepts, while the bottom section provides a feature-by-feature index of each API capability:

Use Examples to Support Understanding

Who doesn’t love a good example? Examples can make concepts and features much easier for devs to understand, especially around areas that are unique to your tool. Even comparatively simple functions should include examples as this provides extra clarity to developers and prevents uncomfortable doubts from arising.

Examples should be easy to find, ready to run, and approachable for those who’ve never experienced your tool before. Incomplete examples can create more confusion than they solve as developers might not yet have enough background knowledge to be able to fill in the gaps.

You should include examples in line with your quick-start guides and technical reference information to help contextualize what you’re describing. It’s also useful to prepare a cheat sheet of examples for your tool’s most commonly used operations. Command line HTTP client HTTPie does a good job of succinctly illustrating how to achieve key use cases, for instance:

Where possible, try to favor the use of interactive examples that are embedded into your content. These allow devs to observe features in action without leaving the docs, creating a more intuitive and satisfying experience. The web platform documentation on MDN illustrates this pattern: examples are clearly signposted in the content, including interactive Play buttons that open the code in a live playground environment:

Provide a Convenient UI/UX

The way in which docs are presented is almost as important as their content. Select a clean UI that’s easy to use and well optimized for readability so developers can easily find and digest your material. Setting up a dedicated docs site provides a more sophisticated experience than relying on wikis and plaintext files while creating an opportunity to showcase your brand style and design expertise.

A specialist docs interface also facilitates the use of more powerful capabilities that produce a more convenient developer experience. For example, you could link your docs site to your developer accounts system, then customize your code samples so they include real account values after developers log in.

The Stripe API documentation uses this technique to good effect. Once you’re logged in, the API keys and other configurable values shown in the docs are fetched from your account. You can copy and run the examples without having to manually alter any options:

It’s also good practice to let developers persistently select the client library, programming language, or integration type they’re using. This allows irrelevant information to be filtered out, making it easier for developers to focus on the steps that apply to them.

Prioritize Search and Navigation

In whatever way the documentation is published, it needs to be supported by a clear navigation structure that makes it obvious how to jump between different content types and topics. Establish a logical pathway for users to follow, from the guide to getting started through to the in-depth reference material, but ensure it’s always possible to skip to specific areas when developers already know what they’re looking for.

Use links—both internal and external—to tie topics together. This lets devs effortlessly discover more information that’s related to the topic they’re reading. Similarly, adding a table of contents at the start of each topic and section aids readers in quickly gauging whether they’ve reached their intended destination.

Discoverability is key to the success of documentation, so it’s crucial to integrate search functionality extensively throughout your docs system. Search needs to be fast, accurate, and capable of surfacing material from all your content sections as users are likely to rely on it to reach the topics they’re looking for. A powerful example is Docker, which lets you open their search panel from anywhere using a keyboard shortcut and then neatly groups all the matching pages based on content type:

Furthermore, optimizing content for search engine visibility provides more paths into relevant content, including when developers are still evaluating different tools within the marketplace. SEO for docs is similar to other evergreen content types: add correct HTML meta tags to your pages, use descriptive URLs and headers, and avoid indexing any autogenerated reference material that might trigger a search engine’s spam or AI detection algorithms.

Shareability is another navigation aspect to consider. Making headers into anchors that act as link targets allows devs to more conveniently reference specific parts of your documentation in chat messages, work specifications, and comments on issues and pull requests. This reduces time spent hunting for information, leading to a more satisfying and productive developer experience.

Conclusion

Focusing on documentation quality ensures devs have the simplest possible experience as they use your tools. Properly formatted, easily navigable docs that provide an exhaustive reference for available capabilities—alongside accessible getting-started guides—keep devs productive, improve retention, and reduce the volume of support tickets you receive.

Creating good documentation takes time, but the benefits more than offset any investment you make. As you’ve seen in this article, many of the most successful developer-oriented tools and platforms have prioritized their docs, ensuring newcomers can quickly find accurate answers to their questions while more experienced users have a clear route to the precise technical info they need. In a crowded marketplace, documentation quality can sell your tool over a competitor’s, so implementing the tips shared here will help improve your business outcomes.

Since I started Draft.dev, our team and the number of clients we work with has grown a lot. With this growth has come the need for robust, consistent processes that help us ensure that each client gets the absolute best, highest-quality technical content possible.

One thing I value in our interactions with clients is transparency. We need clients to be transparent about their expectations, and we have to be transparent about our timeline and capabilities. In other words, if we can’t do what a client needs, we’ll tell them.

Our Process for Working with Clients

In the further interest of transparency, I’m going to share our entire client onboarding process as it stands today. While things occasionally deviate, you might find it helpful to see the whole thing laid out. Hopefully, this gives you a better idea of what to expect as you consider or start your engagement with Draft.dev.

Typically, onboarding takes 6-9 weeks between when we sign a statement of work and when your first article is completed.

The timeline may increase if we’re fully booked though, so be sure to check with us if you need hard deadlines.

1. Discovery Call

Before we begin working with a new client, we want to make sure we’re a good fit for you. In our 30-minute discovery session, we’ll ask you where your business is at, what your content goals are, and the type of content you’re looking to produce.

Based on this call, we’ll follow up with samples of our various types of content and next steps, or we’ll refer you to another content provider who’s a better fit.

2. Statement of Work and Timeline

We almost always have a backlog of new clients waiting to start, so once you’re ready to reserve a spot in our production calendar, we’ll send over an estimated timeline and statement of work. This allows us to ensure we have enough writers and editors ready to help maintain our rigorous quality standards, and that both parties are on the same page as far as the scope of work is concerned.

3. Topic Strategy and Intake

During the topic strategy phase, we’ll define your content goals, requirements, and the preferences of all stakeholders on your team. Your team will be able to provide examples of articles you like and any desired topic ideas you have in mind. All relevant information about your brand and content strategy is helpful to our Technical Content Specialists and can be incorporated into your content plan.

Some clients already have an idea of what topics they would like covered, but don’t worry if you don’t have any; this is not required. Our Technical Content Specialists will create multiple topic clusters through search engine keyword research and community-based research for your team to review and approve. Our topic strategy process typically takes a week.

4. Approve Briefs and Outlines

With topics in hand, we’ll create detailed briefs and outlines for each piece. By breaking down each post and detailing the exact expectations before we start writing, we can ensure that expectations are clear for our writers and editors.

Once you approve the briefs and outlines, we’ll get them into our CMS and send over a finalized production schedule. Typically, this won’t deviate much from the proposal unless you need more time to review and approve the briefs.

5. First Payment

When we lock in your outlines, we’ll arrange a payment method with you. We offer quarterly payments by default or monthly payments for a small premium. Most clients pay by credit card or bank transfer, but we can accommodate custom invoicing options as well. Usually, the first payment is due 30 days after signing the statement of work.

6. Production Starts

At this point, we’ve already started recruiting writers, and now that your briefs are in our system, we will start assigning them to our writers. Because our writers are practicing software engineers (most with day jobs), you’ll likely have several writers assigned to your content over the course of the engagement. Our skilled editing team and technical content specialists ensure that the quality and tone of each piece are consistent with our style guide and your preferences.

Finally, if your piece requires custom illustrations or application diagrams, our in-house team creates the assets you need. The goal is for each piece to come back to you ready to publish.

7. Delivery of First Article

Your first article will usually be ready around four weeks after your briefs are approved. Additional content rolls in after that. While we invest a lot of time planning out content with each new client, we expect to accommodate minor revisions on the first article or two as we figure out your style and preferences.

You have two weeks to request revisions for each article with two rounds of revisions available, as it’s important to us that our content meets your expectations.

8. Content Promotion

Upon completion of your first article, your account manager can provide guidance on how to promote your content through social media best practices, ensuring that you are maximizing your audience reach. We will provide you with social media collateral for each of your articles so that you can easily promote your content across all major social channels, including Twitter, Linkedin, HackerNews, and Reddit. By streamlining your promotion efforts with our recommended social media automation tools, you’ll be able to schedule your social posts within minutes after you publish your article.

9. Repeat

After the first article is sent, you’ll start receiving new content every week (sometimes multiple times a week) based on your production schedule. We work hard in the planning process upfront to ensure we can deliver content consistently. That said, we do occasionally need to swap the order of articles based on writer availability and expertise.

About halfway through your first three-month engagement, we’ll start to talk about coming up with more topics and renewing your plan. Pending a signed renewal, we’ll work with you to start on the next batch of content to minimize or avoid production gaps.

Frequently Asked Questions

While that covers the basics, you may have a few questions. Feel free to book a call with us or check out some of our FAQ below.

How quickly can you get started?

Because we’re a service-based business that relies on real humans to write and edit each article, we can’t start overnight. Typically, it takes six to nine weeks between signing our Statement of Work (SOW) and receiving your first piece of content.

What if we don’t know any topics to write about?

You came to the right place. We use a proven method for generating topic clusters around keywords relevant to your business. This will help you rank highly in search engines for terms that your readers are likely searching for.

What kind of articles can you write?

Broadly speaking, we break blog posts down into four types, and we focus on content aimed at software developers, data engineers, technical leaders, and sysadmins.

Typically, we don’t write content that involves inside knowledge of your company or tool, but we can write tutorials based on public-facing APIs or the documented features of your tool. We can also write comparisons, high-level guides, introductions to technical topics, roundups (or listicles), and persuasive pieces.

Do you do ghostwriting?

Yes, but it follows a different process and pricing model.

Our standard content authors are technical experts who write to showcase their expertise and learn new things.

For ghostwriting, we’ll pair you up with a dedicated writer and account manager who will interview you and work specifically on each piece.

Can I start with a trial article?

We don’t currently offer trial articles to prospective clients, but we are happy to send you additional samples. We also offer revisions, rewrites, or refunds if you’re ever unsatisfied with our work.

How much does it cost?

Our service offering starts at $22,000 – $27,000 per quarter, depending on the scope, but we invite you to book a call for the most up-to-date pricing and service offerings. Most clients start with a quarterly 12-post pilot package and renew according to their needs each quarter.

Do you do video tutorials?

Yes, we recently launched video tutorial creation services to all our clients in the developer tooling space. Each package is custom-built depending on your needs with a minimum package size of $20,000 for 6 videos.

You can see a sample video along with more information here. 

Do you do technical ebooks?

Yes, we do offer ebook creation services, but it follows a slightly different process and pricing model than our technical blog post services. You can find more details and specifications on the process here.

Want to Get Started?

Now that you know exactly what to expect when you start your engagement with Draft.dev, I’d love to hear from you. To get started, book a call with us and learn more about how Draft.dev can help you create in-depth, technical content that resonates with your audience.

With the demand for technical content being as high as it is, you might be interested in turning your software development knowledge toward writing. After all, why not? It can be a lucrative hobby if you enjoy writing anyway. You can build a reputation as a voice of authority. It can pave the way toward speaking and presenting, if that appeals. Some developers have even moved on to writing full-time after getting a decent taste for it.

Of course, to get that far down the road, you need people to want your writing. So how exactly do you get asked to keep writing technical articles?

I’ve got you covered. Take your cue from this article, and technical publishers will be piling requests into your inbox.

Hit Your Deadlines

Hands down, bottom line, if you take one thing away from this article, make it this tip. Effective content marketing means publishing on a schedule. Whoever’s in charge of that schedule (usually a content manager) has their own deadlines to hit. They’re trying to reach their own content quotas.

Help them do their job by consistently delivering your writing on time.

I get it, hitting deadlines consistently is hard, especially when it’s not your day job. Sometimes life gets in the way. If you want to make writing a serious part of your career, try to make sure a missed deadline is a rare exception to the rule.

If you can hit your deadlines and deliver adequate work on time, you don’t have to be the best, and you’ll always have writing work.

Understand What You’ve Been Asked For

Every writing assignment should come with a few basic pieces of information:

• your due date
• your pay rate
• how big the article should be (usually a word count)
• any other deliverables (images, video, author bio, etc.)

Make a note of everything you’ve been asked for and make sure it’s all submitted properly.

Speaking of submission, your publisher may have a specific method for accepting your finished article. Do you drop it into their CMS? Email someone a link to a Google Doc? This, and other information, may be available in a style or process guide.

If your publisher has a style guide, read over it and try to follow it. You don’t have to be an expert on their particular style for your first article, but the more you try to adhere to the instructions you find, the more likely you’ll be asked for a repeat performance.

Be Ready for Revision

Here, I have to expound on the previous tip. Revisions are part of writing, and your publisher may have outlined expectations around that for you. Check your contract—is there language about how many revisions you can be asked to do for the pay rate you’re receiving? One revision is common, but be ready for two if you’re writing for an agency with its own end client.

It’s essential to know your publisher’s revision process for a couple of reasons:

• You can decide if the offered pay rate is sufficient once you factor in revision time.
• You can point to a specific boundary if your publisher keeps asking for revisions.

Note: hitting deadlines applies to being timely with your revisions, too!

Your revision will most likely entail answering questions from either an editor or a technical reviewer. Be sure to respond to every query, even if it’s just to disagree with a suggested change politely.

Communicate—But Be Smart About It

If the organization you’re writing for has an established content publishing system, chances are good they’ll have a lot of answers already prepared for most questions you might have.

Before you send an email to your editor with a list of questions, double-check if you’re asking any of these:

• When’s the deadline?
• When and how do I get paid?
• What’s your editing process?
• How many revisions do you ask for?

All of those are legitimate questions. But first, take a stroll through your publisher’s website or any emails they may have sent you when you first connected. If you have a formal contract (and you should), read through it. All of it.

You might find your answer faster there than sitting in someone’s inbox. And content managers love working with freelancers who can find their own answers.

However, you may have one of these questions:

• Can I get an extension?
• Can I get some help on this technical roadblock?
• I think I need paid access to this tool—can you help out?
• To cover this topic, I think I need a higher word count. Is that okay?
• Can you help with a problem with a payment?

Especially if it may affect your due date, be sure to get these questions asked as soon as they occur to you. Changes are more problematic to accommodate the later in a schedule they appear. You’re more likely to receive a positive response if you’re not putting your publisher into a time crunch.

Learn to Self-edit

Last but not least, perfect your writing. Strive to improve next time after receiving a round of feedback or edits. Pay attention to what’s been adjusted upon publication and, within reason, try to handle that on your own ahead of time.

If you’re being asked to supply a 1500-word article and your Google Doc is well over 3,000 words, go over your article with an eye for cutting out the fluff. Are you being repetitious? Are you trying to cover too much? Whoever edits your article will appreciate you taking the time to clean your work up before it reaches them.

But self-editing isn’t just about making things easier for your editor. It’s also about protecting your work. Your complete message is more likely to make it to publication if you don’t leave a mess for an editor to push into shape.

Think of editing like house cleaning. Sure, you may hire a cleaner to come in. But if your sink is full of dirty dishes, they’re probably not going to be able to clean the sink. If your kid’s toys are all over the floor, the professional cleaner may not have time to vacuum.

Leaving messy writing for someone else to fix is kind of the same deal. Your article will probably not look super polished if your editor is trying to shove your metaphorical toys in a hall closet.

Obviously, the writing that goes into your article is the most important thing to pay attention to here, but don’t neglect your email communication! If you want to present yourself as a professional writer, try to use standard spelling, capitalization, and grammar at every opportunity.

Conclusion

Adding technical writer to your LinkedIn page isn’t as much about being a great writer as you might think. Like most jobs, your success as a technical writer boils down to how difficult you are to work with. Do you make your editor’s job easier? Are you reliable with your deadlines and the completeness of your work? Are you efficient and professional in your communication?

At the end of the day, that’s what will keep the writing requests filling your inbox, I personally guarantee it.

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.

Ever since I started Draft.dev in 2020, one of the most common requests we’ve gotten from prospects has been video production. Unlike our content writing services, video was an area where I had little to no professional experience, so I was wary of taking it on without the expertise available to do it right.

Fortunately, as our team has grown, so have our capabilities. I’m excited to announce that as of this month, we’re offering video tutorial creation services to all our clients in the developer tooling space.

Here’s an example of a video we did for our own content recently:

Learn more and book a call to discuss video tutorials here.

Why Video?

Our success at Draft.dev is largely due to the fact that we focus on doing very few things, very well. We only produce technical content for companies trying to reach subject matter experts.

Most marketing agencies can’t resist the draw to become full-service providers for their clients, offering everything from branding to design to ads to content. Draft.dev is different because we intentionally say no to all those other forms of work in favor of doing fewer things better.

So, I didn’t take the decision to add video content to our list of offerings lightly. But I also want Draft.dev to be the premier content creation company for developer tools brands, so I knew we’d eventually need to have it. There’s a lot of reasons clients want video tutorials, but a few include:

• Supplement SEO – Written content with an embedded video tends to have higher time on page and a lower bounce rate. This in turn helps Google recognize the value of your content.
• Reach younger developers – While my generation learned on text-based platforms like Stack Overflow, developers coming out of school today are more video-native than ever.
• Improve social reach – Social platforms like TikTok and YouTube are extremely popular discovery platforms, and even text-based platforms like Linkedin and Twitter are doing more to support video than before.
• Augment documentation – Text-based documentation is the standard among developer tools companies, but video is quickly becoming an expected addition. Having videos to supplement documentation will be essential in the coming decades for some of the same generational reasons above.

Why Aren’t More Developer Tools Companies Using Video Today?

Video tutorials are incredibly hard to do well and even more so at scale.

Clients are often surprised by how well we do written content because they know writing for developers is notoriously difficult, but video adds another level of complexity. You need at least four different roles to do video work well, but most companies can’t justify making all these hires:

• Engineer to create the tutorial
• Another engineer to test and verify the tutorial
• Editor to create the script
• Engineer to record the video
• Video producer to add visuals, transitions, and effects
• Voiceover actor to read script

Obviously, you can compress a few of these roles, depending on each person’s skills, but then you run into a question of time utilization. Does it really make sense for a software engineer to spend 8 hours editing and producing a video? Can you afford to skip testing when it means you might have to re-record the whole thing because you find a bug in 2 months?

How We Create Technical Tutorial Videos

Similar to how we produce written content, our philosophy with videos is the same:

Find experts in each step in the process and hire them to do the part of the work they do best.

This allows each of them to focus on their area of expertise and ensures that our team can cover a wide range of technologies while keeping costs down.

With over 300 engineers in our writing pool, there were plenty who had some video experience and the software necessary to record tutorials. Two of our editors also had experience writing scripts, so we were able to build that capacity quickly.

Finally, I bought an audio and video production company earlier this year, and part of the reason was that they’d be able to do the video editing and post-production work that I didn’t know how to do yet. Their expertise has been invaluable as we explore adding short-form and long-form video to our offerings.

I’m really proud of all the work our team at Draft.dev put into figuring this out. If you’d like to learn more, please book some time with us here.

In 2020, I started exploring AI writing tools. I recorded a screencast back then on how you could use GPT-3 to create or at least help you create a technical blog post. In 2021, I recorded a more in-depth comparison of the AI writing tools available at that time.

It’s interesting to compare the two videos because you can see how much better these tools got in just a year. That said, all the tools I tried in 2020 and 2021 were clunky. They seemed to push in the direction of writing entire blog posts for you, but they couldn’t get beyond surface-level definitions of terms and often introduced factual inaccuracies.

In 2022, OpenAI released Chat GPT, and by early 2023, it had hit the mainstream. Everyone from clients to writers to family members asks me about AI writing now, so I thought it would be worth putting down a short summary of my thoughts and the role we see these tools playing at Draft.dev.

TL;DR: We believe in embracing new technology and learning how to use it.

In their current state, AI writing tools cannot replace the writers we work with (engineers with deep subject matter expertise), but we are exploring these tools and how using them could make sense.

A Brief History of AI Writing Tools

The well-known generative writing tools available today (like GPT-3 and more recently, GPT-4) use large language models (LLMs) to summarize or generate text based on existing text datasets. In other words, they “read” content on the internet and use it to surmise patterns that allow them to write new content.

LLMs are a form of neural network, a concept that’s been part of machine learning for at least 40 years, but the big unlock in recent years has been cheaper access to computing power and storage. While it’s not trivial to crawl enough of the internet to build one of these things, Google’s been doing it since 1996, and as you might imagine, they’re not the only ones gathering data.

As the ability to collect and store text data improved, so did the availability of computing power to compute the strength between nodes in this data. The technical details go beyond my understanding, but essentially, LLMs today are trained on trillions of words to calculate the relationship between them and “learn” to use them.

AI Writing Today

This technology is changing (and improving) rapidly, but as of March 2023 when I write this, the best general-purpose consumer-available AI writing tool is OpenAI’s GPT-4 (the model used by Chat GPT).

It can do amazing things like write a short poem about the recent collapse of Silicon Valley Bank in the style of Charles Bukowski:

The Valley once glittered with gold,
But greed took hold, and fortunes were sold.
Silicon dreams turned into a nightmare,
As the bank collapsed, leaving despair.

Investors panicked, accounts were drained,
The system failed, and hope remained.
Bukowski saw it all before,
The rise and fall of money's allure.

The Valley's tech giants brought hope and change,
But the price we paid was out of range.
The crash of '23 was a bitter pill,
And the wounds may take years to heal.

But in the rubble, we'll rebuild anew,
The spirit of innovation shining through.
Lessons learned, the future bright,
As we rise again with all our might.

Or describe the feeling that an ancient Greek stoic would have while falling off a cliff:

I strive to maintain a state of inner calm and rationality regardless of external circumstances. Therefore, as I fall off a cliff, I focus on accepting the inevitability of my fate rather than giving in to fear or panic.

I remind myself that death is a natural part of the cycle of life, and that my consciousness will simply return to the universe in a different form. I reflect on the impermanence of all things and the idea that my time on this earth was always limited. I find solace in the knowledge that I lived a virtuous life, true to my principles and values.

As I approach the ground, I feel a sense of detachment from my physical body and a deep sense of peace. I trust that the universe has a plan for me, and that whatever happens next is simply part of that plan. In this moment, I am at peace with my fate, knowing that I lived and died according to my own code of ethics.

What AI Writing Doesn’t Do Well

But it’s not perfect. The current iteration of GPT-4 isn’t updated with real-time data (although that’s coming soon), and it often states factual inaccuracies confidently without citing sources, so it’s essential to have a human in the loop.

AI experts caution, however, that such tools should only be used to support people who are already experts in their domain. Generative AI has been shown to spew disturbing content and misinformation, while other concerns have surfaced over intellectual property theft and privacy. – Karen Hao, The Wall Street Journal

It also doesn’t do well with personal experience or realistic examples, especially in niche topic areas (like ours). While you can try to push it to do so, it doesn’t always understand “real life” so it struggles to replicate the human experience.

Finally, it doesn’t do well with extended pieces of text. It struggles to go deeper into topics, so you’ll often find it repeating the same surface-level definition of a topic or spitting out nonsensical jargon because it doesn’t have enough good data on a particular niche.

For these reasons, it struggles at technical depth—one of our main selling points to clients—and it’s nowhere close to replacing our world-class group of software engineers as a writer. As a rule, we push writers to go deeper and add more personal experience when we see it lacking, and we’re planning to use Positional to detect AI-written content going forward.

What AI Writing Does Do Well

That said, we are starting to use GPT-3 in a few specific ways.

We’ve started using it to generate short descriptions of new articles, new variations of titles for blog posts, and even some article outlines. While we still have to guide and fact-check the machine, it’s saving us a few hours of work per week already.

Coworkers have told me they use it to reply to emails, come up with definitions for generic terms, and get started on new ideas. While I haven’t found it useful for writing the actual content of a blog post, it has helped me come up with ideas for items in a list or brainstorm transitions between sections.

Many of GPT-3’s weaknesses are fixable though, so I think we’ll continue using it more in the future. It’s pretty easy to imagine OpenAI including fact-checking and real-time data in future models. Other companies will also be building specialized versions of OpenAI’s generic language models to work better for internal docs, emails, and industry-specific writing. It’s going to be a very interesting next few years in the writing industry.

The Eventual Future

AI writing tools will be for writers like Excel is for accountants.

Great writers (like great accountants) won’t be replaced by AI writers, but will instead learn to work with AI as a virtual assistant to get more done.

Subject matter experts with personal experience and knowledge of the nuance of their field won’t be replaced by AI, but maybe the tools will make writing more approachable. I’d love to see more engineers start writing because tools like Chat GPT make it easier.

Generative AI might also change the way we search for information online. We may be able to interact with search engines through more natural formats like asking questions, and maybe…just maybe…Siri will finally be good at something.

Like Ryan Law recently said, anyone working in content marketing or writing today should be exploring these tools and learning how to use them in their day-to-day. I’d love to hear how you’re exploring and using AI in your writing. Find me on Twitter to continue the conversation.

Before 2020, remote work existed but was not as prevalent as it is today. Truly remote companies, like Basecamp, were few and far between.

Then the pandemic arrived and everything changed. With people in lockdown, companies had no choice but to adapt. Everything from meetings to collaboration to informal chat was now done remotely. There was an adjustment period, but two years later, the remote-working model has proven to be successful.

By allowing employees to work from their home offices, co-working spaces, or even coffee shops, companies gave employees the freedom to work more productively. For example, people who work from their homes were able to reduce the interruptions and noise that traditionally happen in an office. People with children were able to pick up their kids from school and finish their workday later at home.

Obviously, remote working doesn’t come with benefits alone. When employees could just walk to a colleague in the office, communication now requires a Slack message or an email. If employees are not quick to reply, there can be delays. Loneliness and disconnecting from the mission of the company is something that managers also need to be aware of.

That’s why distributed teams need to have the right tools to keep working effectively. From organizing and carrying out meetings to collaboration, this article discusses seven tools that can help your team succeed in a remote-work environment, including Zoom, Status Hero, and Jira. These tools have been chosen due to their ease of use, customizability, and support for different time zones.

Remote-Working Tools

Since the pandemic, a slew of tools have been created to assist companies and their teams in a remote-work environment. However, not all of these tools are easy to use or customizable. In this section, you’ll learn about the tools that will help your remote team function well.

Conduct Meetings with Zoom

It’s hard to talk about work without mentioning meetings. Even if you are a solo entrepreneur working from your basement, you’re probably subjected to meetings on a regular basis.

Thanks to the pandemic, Zoom quickly became the preferred videoconferencing tool of companies across the world as they needed a way to continue meeting remotely. It offers features like waiting rooms to allow hosts to decide when participants can join, breakout rooms to divide participants into smaller groups, and the ability to record meetings.

Breakout rooms, in particular, are very helpful. In a remote environment, it can be hard to have informal chats with your colleagues unless they are scheduled. This is why if you have a weekly meeting with your team for a status update, for example, it can be helpful to start with a small informal chat. If you have a big team, breakout rooms can be a great tool to divide and let them chat about their weekends for a few minutes before starting the meeting.

The recordings are also beneficial for people who are in different time zones or weren’t able to attend a meeting for one reason or another.

Overall, Zoom is easy to use and comes with a lot of additional features even on the free plan.

Organize Your Daily Updates with Status Hero

Most companies have regular check-ins to follow up on projects and touch base on any questions team members may have. What tool you decide to use will highly depend on your team’s communication style. If you work remotely but synchronously, then your stand-up is probably done with everyone present at a specific time. In this case, Zoom is your best option.

However, if you want to reduce the number of meetings and push asynchronous check-ins, then consider using Status Hero. The goal of Status Hero is to turn long and sometimes unnecessary stand-up meetings into a concise report for all team members to review. What would normally be a twenty-minute meeting where people list what they have done one by one is instead turned into individual reports where people clearly list out what they have done and will do and, more importantly, highlight blockers. With Status Hero’s numerous integrations available, you can integrate data from your other tools such as Zoom, Asana, or Jira and see what your colleagues have done in the last twenty-four hours.

Manage Your Project with Jira or Asana

When it comes to project management, there are so many tools to choose from that it can feel overwhelming. In this article, you’ll look at two options: Jira and Asana.

To say Jira is easy to use would be an exaggeration. The learning curve to getting used to this tool is not negligible. However, once you get used to it, what Jira sacrifices in ease of use, it definitely makes up for in features.

Jira is highly customizable, letting you create fields and automated processes. For example, you could set up a process such that when creating a bug, the technical support has to fill out a few fields like the number of customers impacted or which area of the product is impacted. Once created, that bug could automatically receive a priority (low, medium, or high) and be assigned to the right development team. This kind of process saves a lot of time in the long run, which is why Jira is a popular product among big companies such as HubSpot, Zoom, Bloomberg, CBS, and more.

However, if you’re a smaller company, Asana might be a better fit. While not as feature rich as Jira, it’s very easy to use. It has an aesthetically pleasing and intuitive user interface. Whether you work in IT, marketing, or sales, it comes with a bunch of templates for you to choose from. It’s an excellent project management tool for companies who don’t need all the bells and whistles of Jira but want access to straightforward boards, lists, and timelines.

Collaborate with Google Products

Google products need very little introduction. With Drive, Docs, Sheets, and more, Google offers tons of tools that are great for collaboration. Whether you’re working on a proposal or a presentation, Google has a product for you. Many people use it in their personal lives, so introducing Google products to your team is painless.

With Google Docs, you can even leave comments and suggestions, making the collaboration process easy for teams working asynchronously.

Document with Confluence

While Google is a great tool for collaborating, searching through Drive can get complicated. This is where a tool like Confluence is a great option for documenting processes and more.

When a company reaches a certain size or age, it’s important for employees to start documenting company knowledge. This can include product knowledge as well as processes, technical investigation, and internal decisions. This documentation will be helpful not only for new employees but also for older employees as they leave the company. It’s important to have this knowledge written down to have a better overview of how your product works and why certain decisions were made.

Like Google Docs, Confluence is easy to use. You can quickly create pages, format them, and leave comments to collaborate during the documentation process.

Communicate with Slack

When it comes to communication, it’s hard not to mention Slack. Even before the pandemic, Slack was an incredibly popular communication tool. With its attractive interface, Slack is very intuitive and easy to use. On top of their chat feature, they have recently started introducing more features such as calls and huddles to allow you to organize meetings without leaving.

Slack also supports a lot of integrations, including Jira, Google products, Salesforce, and GitHub. Regardless of the tools you use, you can probably integrate it with Slack.

Conclusion

[Remote working is a great model] (https://draft.dev/learn/becoming-a-remote-technical-writer). It has given more flexibility for workers to do the job in a way that is most comfortable to them and provides for a better work-life balance. However, in order for things to run smoothly, certain tools are necessary.

In this article, you learned about tools like Zoom, Status Hero, Jira, Asana, Google, Confluence, and Slack. All of these tools can help you organize your remote team.

In addition, every tool in this article can be integrated with Status Hero. As mentioned previously, Status Hero reduces the number of meetings by prompting teammates asynchronously for daily check-ins. By integrating various tools, you can automatically get a high-level view of what each team member has done.

Publishing high-quality technical content and getting it in front of your target audience is just the start of a successful developer marketing effort. Having a compelling lead magnet can help you turn that anonymous traffic into known names and email addresses that you can continue to build a relationship with over time.

Our compilation ebook offering at Draft.dev is designed for companies that want to create a high-quality lead magnet quickly without the cost of commissioning one from scratch.

How it Works

After you meet with our editorial team, we’ll take 2-4 of your existing blog posts (either pieces we wrote or content your team created previously) and re-edit them into a single cohesive work. We’ll include a cover (based on a stock image), custom colors, and any relevant screenshots or graphics from the original content.

Once we finish the re-edit, we’ll send it to your team for revisions or approval. While heavy revisions aren’t typically needed since we’re using existing content, we’re happy to include two rounds of revisions in the standard price.

FAQs

What if we have custom fonts or a style guide?

We offer custom colors and can include your logo on the cover, but if you want more sophisticated design work, we’re happy to share the content with your design team so they can customize it further.

How long does it take?

This process generally takes just 1-2 weeks after the original content is written.

Can I order an ebook alone?

While we don’t offer one-off ebook production at this time, ebooks can be rolled into an existing technical content plan or as part of a statement of work for a new client.

Do you have any examples of this kind of compilation ebook?

Sure! This ebook for Backhub is a good example of our work.

To discuss our packages and pricing, please book a call with us here.

What if we don’t already have content to turn into an ebook?

We’d be happy to help you produce a series of blog posts that will make a good compilation ebook. We produce hundreds of pieces of content for developer tools companies every month, so we’re happy to help with content production as well.

Next Steps

To discuss our packages and pricing, please book a call with us here.

And, if you need a custom whitepaper or ebook that’s beyond our offerings, we’re happy to refer you to one of our recommended partners.

Let me be honest, I don’t like the term, “Thought Leadership.” It’s too vague. Marketing people often apply it to writing that is neither thoughtful nor leading anything.

For example, a lot of people refer to high-level, informational writing (like this overview of Docker Networking we wrote for a client) as “thought leadership.”

While the piece above is excellent, it’s not really conveying leadership. It doesn’t have a strong point of view, and it’s not borne out of a unique perspective on the state of DevOps. It’s just really deep, helpful information on a highly technical topic. Great stuff, but not “thought leadership.”

So, what is true “thought leadership?” And how do you write effective technical thought leadership content?

In this piece, I’ll offer my perspective. As a former CTO turned writer, I’ve written a fair bit of technical thought leadership, but I’m also an avid reader of the stuff. After sharing some examples of technical solid thought leadership, I’ll offer a few tips for writing your perspectives in a way that is both thoughtful and persuasive.

Examples of Technical Thought Leadership

Good thought leadership blends your unique experience and expertise with writing that’s compelling to readers.

For technical thought leadership, that means you showcase an understanding of a specific technical subject while either making your case or showing something you’ve learned.

I’ve noticed three broad categories of technical thought leadership:

1. Taking a Controversial Stand

Not every “hot take” on the internet is thought leadership, but some of them are. You are taking a risk by taking a hard stance on a somewhat contentious issue, but you’re also more likely to generate some buzz.

Some examples include:

• Is it OK to change code for the sake of testing?

• Starting a business around GPT-3 is a Bad Idea

• The bulk of software engineering is just plumbing

In these examples, the writer combined industry and technology knowledge with a hard stance that isn’t universally held. Ultimately, they each make a good argument, whether you end up agreeing with the author or not.

2. Sharing a Unique Point of View

Another way to demonstrate thought leadership is by sharing a unique point of view or insight into something you’ve learned. I like these when they go deep into something I didn’t even know I cared about (like in the 32 bit real estate piece below):

• ​32 Bit Real Estate

• No code reviews by default

• A Day in the Life of an Engineering Manager

These informative articles usually showcase the writer’s expertise to build trust while giving readers insight into their point of view. They’re often popular with others who have experienced similar things but may not have had the skill or time to write them down. For example, my “Day in the Life of an Engineering Manager” piece above made the rounds on Reddit and Hacker News with lots of head nods from other engineering managers.

3. Predicting the Future

Finally, a lot of thought leadership is directed towards the future. Engineering leaders at large companies, consultants, and visionary startup founders often present these kinds of pieces as a way of swaying readers towards their worldview.

• The Future of AI: How Artificial Intelligence Will Change the World

• The Modern Data Experience

Sometimes these pieces are controversial, but they often look far enough into the future that nobody will remember if the author was wrong anyway.

How to Write Technical Thought Leadership Well

With a sense of the various types of technical thought leadership writing out there, I’d like to give you a starting point for creating compelling content like this. Besides getting some of the fundamentals of technical content down, there are a few extra things you can work on to make your thought leadership stand out.

Experience

This might be obvious, but your writing will always be more compelling when you pick a topic you have experience in.

I’m not saying freelance writers can’t write decent thought leadership content, but if you don’t have personal experience, you need to get sources and be ready to dive deep into this topic.

With technical thought leadership, this is especially important. Who wants to read a piece about the future of edge hosting by someone who’s never used deployed something to it before? If your audience is experienced technical leaders, you need to have the experience to back your writing up.

Up-to-Date Knowledge

Technical fields change quickly, so check out the existing content on the topic before you start writing. Books, blog posts, and industry news can all help you understand more of the context surrounding your observations and help you create more complete arguments.

Support a Single Thesis

With experience and knowledge in place, you want to write your whole piece with a single thesis in mind. Many attempts at thought leadership turn into scattered rants that ramble through seemingly unrelated ideas as they go through the author’s head.

Take a single strong stance on each piece. Make sure everything you write supports that stance.

Supplement Opinions

“In the hands of a good writer, data-heavy content is both informational and fun. Research skills are just as important as creativity — together, they make all of your content attractive and engaging.” – Duke Vukadinovic, FirstSiteGuide.com

A lot of the thin thought leadership content is pure conjecture. The author may have personal experience, but it’s tough to take them seriously if they don’t back it up with data, quotes, logical arguments, or respect for the other side.

I have started interviewing a few sources for most thought leadership pieces I write. This almost always results in more robust ideas as I end up collecting multiple points of view that might vary from my own.

In persuasive writing, be sure to refute yourself then resolve the argument. By pointing out that the other side is somewhat valid, you gain credibility with those on the fence.

Craft Strong Conclusions

Last but not least, you need a solid conclusion to drive your technical thought leadership home. In some cases, this could be a call to action or encouragement for readers to consider this topic more independently. In others, it could be an invitation for rebuttals.

Ideally, you want people coming away from thought leadership pieces with a new perspective on the topic at hand.

There’s No Substitute for Experience and Time

While you can research a topic, interview experts, and sink a lot of time into thought leadership pieces, I’ve found there is no substitute for real-world experience. Suppose you’re an executive spending hundreds of hours per month thinking about a topic. In that case, you’re inevitably going to have better opinions about it than someone who just picked up a cursory understanding last week.

If you find yourself struggling to write thought leadership content, you might just need more time to think. I’ve used various tactics to make time for organizing my thoughts, and I find this to be a great time to formulate opinions and arguments that might make good thought leadership someday.

Finally, if writing skill is your blocker, you don’t have to use this medium. Video, audio, presentation, etc., can all be good ways to get your thought leadership out there. While written communication is essential, it’s not the only way to get your point across.