The Developer Advocate's Guide to Content Creation

November 24th, 2021

Have you ever felt overwhelmed by the idea of having to create that next blog post or YouTube video? Do you find yourself unable to finish things because you’re not quite sure when to call it done? Are you adjusting your outlines or talking points on the fly?

Many developer advocates experience these issues, myself included. Content creation is a fundamental skill set unto itself, and it’s easy to get caught up in feeling like you’re stuck or ending up with content that isn’t of the quality you would like.

Learn how to create content more effectively by doing the work before the work: properly scope your content, pick the suitable medium, how to get quality feedback, and how to capture your audience.

⚠ This post focuses on what to do once you already have a topic. It does not cover how to figure out what content you should be creating!

Doing the work before the work.

One thing that really messed me up when I first started creating content was that I thought it was all about feeling super motivated and sitting down in front of an empty document and then creating amazing content based on inspiration and … I don’t know what else honestly. Because I had absolutely zero ideas about what made good content.

It turns out good content is a lot less about being inspired to create content and a lot more about creating content that is appropriately scoped, provides the right level of detail, and has a clear outline and goal.

Over the last two years, I’ve had the honor of working with Khalil Stemmler, one of the best writers I’ve ever met, and he put me on to a framework for writing that fundamentally changed my approach to content creation. Khalil helped me realize that the biggest issue with my content (there are many others, I assure you) was that I wasn’t doing the work before the work.

Creating content is a lot like creating software. If you don’t know the requirements and constraints of the system (or piece of content in this case), it will be challenging to assess completion properly, and you might not end up with the result that best fits the need.

Content Pre-work Checklist

I’ve distilled my learnings into a five-part checklist I use for every piece of content I create. The first three parts: Objective, Motivation, and Persona, help you properly scope the content. The last two parts: Hook, and Questions, help you formulate a compelling opening and content outline.

The illustration shows five steps to the left. Three of the steps (Objective, Motivation, and Persona) are grouped under "Content Scoping" and the other two options (Hook and Questions) are grouped under "Content Discovery."

Content Scoping

The first three parts of the checklist are used to define the scope of the content. Having a clear scope in mind will help you stay on track and provide the acceptance criteria for completing the content.

Objective

The objective is the goal of the content. What is this content needed? Are you addressing a developer pain point? Are you sharing a new mental model or raising awareness of something? Every piece of content should be attached to a clear goal. Examples:

Raise awareness of a new product.
Address a specific developer pain point.
Share best practices.

Motivation

We know we’re trying to reach a specific goal, but how do we do that tactically. Think of this as the call to action for your content. What should people walk away with, or what action should they take once they engage with your content? Examples:

Try a new feature that solves their problem.
Sign up for an event.
Build with best practices and inform others.

Persona

Who are you creating this content for? Knowing the audience makes it easier to use the right messaging and helps you identify any prerequisites, as well as give you a rough understanding of how much adjacent content you’ll need to explain in relation to your topic.

For example, if you know you’re about to create content for experienced Node.js developers, you can add experience with Node.js as a prerequisite and skip any explanations of what Node.js is. However, if the Persona were developers new to Node.js, you would want to take great care to define any related vocabulary and make no assumptions about their existing Node.js experience.

Once you’ve completed these steps you should have:

A clear goal (Objective)
A clear call to action (Motivation)
A clear audience (Persona)

Content Discovery

Once the content is appropriately scoped, it’s time to create a compelling opening and do some content discovery to fill in any gaps we might be missing in our original thinking to create a clear outline for the content.

Hook

The hook is the intro and sets the tone for the content. It’s what grabs the audience’s attention, addresses any initial skepticism, and then helps them understand what they will get from consuming your content. Therefore, the hook must be relatable to your audience (Persona) and should clearly define what the content covers.

How did the hook for this post make you feel? If you’re reading this post, then it’s likely true that you related to the questions I asked in my opening and were curious about how to create content more effectively.

Questions

These are the questions you think people might have about your topic, combined with any questions raised during content discovery. These questions provide insight into what the content should contain and form the basis of the content outline.

There are many methods for doing content discovery, but here are some of my go-tos:

Share the hook for the content with others and ask what questions they have after reading the intro.
Make a Twitter thread and see what discussions develop around the topic.
Research other content on the topic and look for questions you have that they aren’t answering.
Check forums, GitHub, and other places for questions folks might have asked about the topic.

Once you have your questions, the goal is to distill them into an outline by looking for logical groupings in the questions and then ordering them appropriately. The end result is the outline for your content.

This is the acceptance criteria for this content, and once all sections are filled out, the content can be considered complete! 🥳

Once you’ve completed these steps you should have:

A compelling hook
A clear outline

Picking Your Medium

After completing the pre-work checklist, the next task is to decide what medium will best support this content. Generally, this will be a decision between making the content a blog post, a video, or a talk. Each medium has it’s benefits and costs, so it’s about figuring out the constraints and then using the medium that best supports them.

Whenever I’m deciding on what medium I’ll use I ask the following questions:

How often will this change?
Is this specific or general knowledge?
What is the timeline for the content?

How often will this change?

Content that needs to change often might not be a great fit for video if there isn’t infrastructure to support updating and republishing video content. Likewise, it might not be a good fit for a talk because you’ll likely have to update it often, and recordings from conferences could lead to confusion if the API changes soon after it’s delivered. However, it could be a good fit for a blog post because that form of content is easier to change.

Is this specific or general knowledge?

Is the topic pretty niche? Or is this a broader topic that requires a higher level explanation? The more specific the subject gets, the less suited it is for videos or talks. Both of those mediums have a high time cost that might not be worth the effort if the content isn’t widely applicable.

What is the timeline for the content?

As much as we should try to avoid hard deadlines for content production, sometimes it’s unavoidable. Sometimes you might find yourself obligated to feature or product release dates. As such, it’s not always possible to use the best medium. If you have an unexpected content ask with a quick turn around, try to default to the minimum viable medium.

Minimum viable medium is the lowest time cost medium you can use to create the content that will meet the goal of the content request. For example, will a Twitter thread work? Maybe a newsletter?

How to Get Quality Feedback

One of the most powerful skills you can develop as a content creator is asking for quality feedback. Rest assured that the quality of feedback you receive is a direct result of who you ask, and what you ask them for.

Understanding Different Types of Feedback

Not all feedback is the same, similarly asking for generic feedback puts the burden on the one your asking to decide what type of feedback you want. Receiving unexpected feedback can really affect your confidence in your work.

For example, let’s say you finished a piece, but you kind of want a bit of positive reinforcement before you ship. You might reach out to a friend and drop a link for them to check out when they get a chance. You might also say something like “would love any feedback you have!” Of course, this person has no idea what you want is positive reinforcement, and they might provide you with feedback about clarity, grammar, or anything else you didn’t expect to receive feedback on. So here you are, ready to ship, and now you’re questioning everything about the content.

Being specific in your feedback requests sets the boundaries of what to look for as well as being more respectful of others’ time. It says, “I really value your input in relation to grammar/structure/topic expertise/encouragement and would love your specific feedback on that area of focus.” It not only shows folks you value them, but it also shows you’ve thought carefully about the feedback you want, and they are more likely to invest more effort in delivering it.

Who should I ask for feedback?

Knowing the type of feedback you need should help you figure out who to ask. If you need grammar feedback, go to the best writer you know. If you need topic expertise reach out to someone with that skill set. Once you have the type figured out, the who should be more precise.

Try not to overburden folks with requests for feedback, especially if it’s not a reciprocated relationship where they are also asking you for feedback. Providing feedback takes a lot of effort, and you can hurt relationships by inviting friends to do too much work for you!

Make sure you’re showing your appreciation of their help and that you never take it for granted! Providing feedback is difficult, you never know how someone will take it. So show your gratitude every chance you get!

When should I ask for feedback?

When you should ask for feedback largely depends on the type of feedback you’re after. For example, if you want feedback on the overall structure, it’s best to ask for that early (like right after you finish your pre-work and have an outline) so that you don’t have to spend time reworking content to fit a new outline. Inversely, if you want feedback on grammar or clarity, it’s best to wait until you’re done with any significant changes to the structure and flow so that you don’t end up needing more grammar feedback later on.

Conclusion

Creating quality content has a lot more to do with doing the work before the work than it does with being inspired to create. While it can still be tough to fill in the blanks when motivation is lacking, having clear scope and a set of acceptance criteria sets the foundation for making informed decisions about what shape the content should take, what medium should be used, and what kind of feedback you should be seeking.