How to Write Truly Great Technical Content (Our Blueprint)

Alex Panagis

I'm Alex, the founder of ScaleMath – a global, distributed customer acquisition & experience agency that helps industry-leading companies grow.

@alexjpanagis

A number of the industry-leading companies we work with at ScaleMath build software for a technical audience. Meaning that for us to reach that audience, we continuously invest significant time & resources to master the art (and science) of writing truly great technical content.

Developers are notoriously known to be difficult to sell to, but that’s because most marketers are so far from developers that they can’t think or understand developers – their tools, the problems they face, and the nuance with which they try to address those problems.

Simply put, if you:

  1. Have a technical product to sell
  2. Sell that product to technical people
  3. Yet aren’t technical yourself

You’ll be starting at a huge disadvantage.

This is true for every vertical, even a marketer trying to sell a project management system to a project manager faces the same problem in many ways, it just so happens not to be as difficult of a gap to fill.

Simply because understanding why a project management system is important is more straightforward than wrapping your head around as well as helping highly technical people make decisions that they base on knowing what they want for specific things they do, without knowing why those things even matter to them in the first place.

So, in this long-awaited and highly-requested guide – we share what we’ve learned from years of actually using technical content as a scalable customer acquisition channel.

1 – The Role Of Technical Content

Before we dive into what actually goes into taking average technical content to good and then subsequently to great – it ­­­­­helps to understand the role that technical content plays for businesses.

If you’ve made it past the introduction of this guide, you should already know subject matter expertise is important.

Yet, for most highly-technical software solutions – technical content is one of multiple facets to a winning content strategy for SaaS companies. It’s evident that you do need technical content to reach a technical audience. To be present as a solution to things developers are searching for.

That being said, the buyer journey – even for some of the most technical products – involves a large number of touch-points between multiple decision-makers all of which have different levels of expertise and different interests. Considering that in many companies, the majority of the leadership team isn’t technical at all. They’re often solely interested in the outcome (and refer back to their team/CTO before having their say in decisions).

As such, there are distinct types of technical content all of which will play an important (not always equal) role for your business…

2 – The Different Types of Technical Content

2.1 – Technical Content for Technical People

Assuming that the end-user of a product consists of a demographic of people that are technical, one type of technical content will be geared towards reaching that segment of potential users as well as existing users that fall into that demographic. Through everything from documentation, tutorials, and content that addresses the pain points that they face in their daily roles & responsibilities (i.e. their “jobs to be done”).  

You can’t fake your way to expertise and it’s extremely easy to tell when this type of content has been put together for the purposes of content marketing rather than a team that knows how to and has the experience to write technical content (something that many SaaS companies we’ve connected with over the years haven’t been able to figure out on their own with their developers).

2.2 – Higher-Level Content for Management & Leadership

Aside from attracting developers, which falls into the category of technical content for technical people – your product will have to reach a management & leadership audience which may not necessarily be quite as technical (at least not in the day-to-day of building features, etc.). Yet, these can interestingly have more decision-making power within organizations.

Higher-level content for management & leadership serves a whole range of different purposes, one of which is addressing what the actual business case for your product is and making that incredibly easy for stakeholders to see as well as understand.

That being said, this is a gross oversimplification that most people abstract this type of content to. Let’s take a look at another great example of a purpose that this type can fulfill when applied to ScaleMath.

A lot of the guides we publish relate to technical concepts in marketing, SEO & content. This category of content often (from the data we have) often reaches people in marketing roles, such as: Head of SEO, Director of SEO, Technical SEO, SEO Specialist, etc. While these roles certainly play a role in the decision-making process – in making the decision to bring in a team of experts to work with to run a software company’s growth, there are other roles involved (a profile we’ve built based on the data of the people & companies that reach out to us). These are often roles in management & leadership that initially come across our work (through content or referral, etc.) and then pass on the lead to their team member who would be responsible for working with us (depending on the size of the company).

So, naturally, there’s a huge opportunity for us to have content that speaks to this person. The same is true for all software companies.

Unless, you really are set on selling to small, individual developers – tieing yourself into only creating technical guides, tutorials, and how-to posts can often hold you back from reaching and selling to companies that operate at an enterprise-level where there are 10 or more people involved in evaluating the choice to use a specific software solution.  

3 – Writing Is Organized Thinking

Organization is an incredibly important part of writing.

It is what sets aside good content from great content. If you’re able to organize your thoughts in a way that is natural to the way a reader progresses through an article and learns about a topic – you create content that leaves readers (even technical ones) with takeaways as opposed to the bad taste that most average marketing content does.

This is especially true for technical guides where you’re teaching relatively difficult topics to an audience that could range from experienced developers all the way to someone just getting started. Each type of person that could land on your post and could be searching for this information should leave with a great experience – finding the piece of information and, at the end of the day, the answers that they were originally looking for.

3.1 – Start With An Outline

Always start with an outline. This is where you begin to research and start organizing ideas and concepts into a cohesive structure for a post.

You may feel like this is a waste of time and have the urge to dive straight into writing. We strongly urge you not to do this.

Spending time (usually no more than 30 minutes depending on the complexity of the topic) developing a great outline actually speeds up the writing process because you’ll spend less time figuring things out, organizing yourself, and coming across new ideas/subtopics you’re thinking about covering as you’re writing. So, you can instead focus on covering what you’ve planned to cover fully and to the necessary level to make this post the very best one out there on the topic.

3.2 – What Goes Into An Outline?

As a general rule, we direct our team (as a bare minimum) to ensure that their outline covers all the H2s and H3s they currently believe (based on the plan) their content will include in order to fully address the topic.

You aren’t forced to abide by the outline if you feel that doing so would come at a cost of making the post the very best one out there on the topic. It is merely a starting point used to essentially pitch your article and showcase what your approach is going to be before you get started.

As you start writing, you will naturally come across new ideas that you didn’t initially consider and shift things around in order to accommodate for them & make the post more helpful.

There are four widely accepted methods for organized writing:

  • Chronologically – the most suitable structure for technical tutorials, how-to guide, etc.
  • In Order of Importance – when comparing concepts and ideas, it can make sense to organize ideas using importance.
  • Problem And Solution – this is typically the best organizational method for technical content that target management & leadership as you can strongly base the whole approach around the problem they’re aiming to address with the solution. But is naturally suitable for every post (since it should always be top of mind when writing to help the reader you’re targeting solve for what they’re trying to solve).
  • Roundups (Listicles) – a good way to organize what is designed to be a post with a simple structure, making it easy for readers to scan.

Grammarly’s guide on organizational tips for writing is a great starting point. However, it is also important to note that these are systems and practices to keep in mind when structuring content. At the end of the day, it’s not a matter of following one or the other, or making a choice. Especially longer posts that serve more than one purpose are likely to have multiple elements to them with parts of the post that are a listicle and parts of the post that are showing a process and are therefore structure chronologically.

The best structural advice for technical content is to build up to concepts. Not every reader that lands on a post will be as technical and knowledgeable about the topic that you’re writing about as you are.

For example, an article about how Docker compares to Kubernetes could start like this:

  • An Introduction To Containers
    • What Is A Container?
    • Why Use Containers?
  • What is Docker and Kubernetes?
  • The Rise of Containerization
  • What Are The Differences Between Docker and Kubernetes?
  • Kubernetes vs. Docker – Choosing The Best Container Solution

While the focus of the article and the goal that we are aiming to address (help the user address) is compare Docker and Kubernetes, we’d still devote time to including a primer on containers, containerization and what the benefits of it are. That way, even someone who’s searching to compare the two topics but may not be an expert on them walks away as more of an expert on them as well as feeling confident in knowing what the differences are, all in all well-equipped to make a decision on which makes sense to use in their scenario.

There is however a fine line between doing this and going off-topic, making your content feel like it isn’t quite as focused. But, this is something that you’ll refine as your write and get feedback on your writing over time.

3.3 – Write To The Level Of The Reader

Your writing should sound like you, yet speak to the level of the reader. Everything from your vocabulary, cadence, syntax and dialect should shine through allowing friends and colleagues to read your voice in their heads as they read. For content, especially technical content to be considered great, you need to develop an authentic relationship with readers.

We encourage and train everyone on our team to consider every piece of content they write as a script that would be suitable for them to present at a mastermind of 20-25 people on the topic that they’re writing about – all of which fall into the ICP (ideal customer profile) of the people we’re aiming to reach with our content (and as a byproduct of that also our solution).

4 – Show People, Don’t Tell Them

One of the worst advertisements I’ve ever seen is Remitly’s YouTube ad that (at the time of writing) is one you encounter quite frequently.

Why? What’s wrong with it?

Notice the line “and we promise it will arrive on time”.

This does nothing but inspire 0 confidence in their service.

Who wants nothing more than a promise?

This is the type of stuff that tends not to slip past anyone who’s even slightly technical. Technical people – software engineers, developers, CTOs, people making decisions that matter, don’t really care what you think.

They don’t want the fluff.

They want the justification. They want the proof, the why (and how)…

And that’s why it’s beyond essential that you’re showing them what’s behind anything you say – why you’re saying it and why it carries any weight. Whether that is in a tutorial about how to do something, in a particular step you do something in a certain way even though there are other ways to do it – this isn’t irrelevant. Lots of the developers reading that are also aware that there may be a slightly different way will be confused if you just ignore the other option as if it doesn’t exist.

Aside from your own writing, there are some additional ways you can support your content as a writer to take it another step further:

Research

Research that supports an idea or a concept (as long as it is not from a competing article. These can be in the form of research conducted by other companies (surveys, etc). Do be careful with what you choose to feature, as it should come from credible companies that you can align with and should also only be used when really relevant.

Quotes

Quotes are great for a whole host of reasons. In short, they break up long blocks of paragraph text and allow you to inject the thoughts share by a credible (and ideally also well-known) source. Verifying quotes and getting them specifically for the purposes of your own posts as opposed to taking them from existing content can be even more beneficial (as they drive attention and interest in your content that can lead to it being shared by the people who are quoted).

Examples

People really like scenarios that they can picture themselves in. Personal experience that is relevant to what you’re explaining not only makes your content more credible, but it also makes it more original than what is already out there.

5 – Join A Talented Team

Working all alone on anything is rarely easy.

This is especially true for technical writing positions. Even more so in the early days when it’s impossible to see any the work you produce have an impact. If you’re a technical writer who wants to join forces with a company that specializes in technical content – we’re hiring! Could today be the day to ditch jugging landing work with delivering to client expectations and praying content will perform & get results? Well, I suppose it very well could be! Feel free to get in touch and let’s talk about it.

After Action Report – Writing Technical Content

Writing great technical content isn’t something you can master in a weekend. At ScaleMath, we’ve been developing technical content processes internally for over 3 years and that process itself never stops. Our team continuously obsesses on improving how we use, produce and distribute technical content day in and day out.

You too can use technical content to your advantage & win.

Encourage your engineering & product teams to start working together with marketing because that’s where the real magic happens and technical content can be taken to the next level. Their knowledge is valuable to building an audience around your product as well as acquiring users. And, once you want to start formalizing and improving how you use technical content for your business, feel free to reach out to us – we’re here to help. 🤝