Technical Writing Guide: Compelling Titles and Subtitles
Draw people in with a well crafted title. Focus their attention with a good subtitle.
Congratulations 🎉
If you’re reading this, you probably want to improve your technical writing skills.
Background:
I’m a Data Engineer with 6+ years experience. I’m also an editor for Data Engineering Things publication.
I review a lot of technical articles and thought I’d share some techniques to improve technical writing.
Problem: Title for Technical articles are tough
An article’s title is the first thing a reader will see — and will determine if people find your content compelling enough to continue reading.
Compelling titles have 2 components:
- Catchiness: pulls a reader in, (an extreme form is clickbait)
- Description: describes content, extreme form is documentation
Generally, you’ll want your title to have some element of “catchiness” to provide indication of your writing style. It’s also important to properly describe your content (think of your readers as a DB cursor, scanning your title like an index, determining if it’s a match for their need).
I. What is a good title?
Easy answer:
It does this → people open your article and be happy that they did.
A good title enables your readers to make an accurate decision about the relevance of your article to their query.
A clever hack is to reverse engineer the query of your reader. For example, when drafting this article I google searched “How to write good title and subtitle for tech blog.” (It returned many compelling articles, and gave me an idea how to phrase this one!)
Some clever titles:
- How To Write a Subtitle That Makes Your Headline Shine
🌞 light, cheerful, descriptive - Title and Subtitle Mistakes Most Writers Make on Medium
⚡️ edgy &catchy! - Get More Readers on the Medium Platform With These Tricks
🏎️ Hack the system vibes
💡 Few of the titles suggested a technical lens — which compelled me to prepend “technical writing guide” to this article.
Let’s get into it how to write a good title.
1. Say the important stuff first. (Order = emphasis)
Order is emphasis. People will read the first 2 words and last 2 words of your title, before deciding to read the whole sentence.
- Put what is most important first.
- Ensure you have descriptive words at both ends of the title
An example: Tools vs. Concepts
Say you are writing an article about real time data architecture and want mention a few frameworks. Which do you mention first?
i. Tools mentioned first:
Apache Kafka, Flink, and Druid: A Popular Real-Time Data Architecture
💡 Readers will expect this article to be centered around Kafka. But it takes away emphasis from the other tools — and the framework.
ii. Concept mentioned first:
Architecting Real-Time Data with Apache Kafka, Flink, and Druid
💡 Readers will expect this article to be about architecting real time data systems. The tools are less important — perhaps the article is suggesting using 1 of them, or all 3 together. This is an enhancement, since it will attract tool-agnostic readers.
iii. Concept first + Action:
Building a Real-Time Data Architecture with Apache Kafka, Flink, and Druid
💡 This is the actual title David went with. Well done!
In general, if your article is about a concept, mention it first.
2. Tools aren’t as cool as what you do with them
When discussing a tool or framework, it’s helpful to think in terms of action — what you do with a tool, rather than it’s name.
Tools aren’t as important as what they do.
💡 Pro Tip: If your article is about a tool or framework, start your title with a verb (or the noun of the outcome).
An example: Delta-rst for Delta table in Rust
Say you are writing an article about the delta-rst package which allows you to write data to delta table format in rust. The cool part is writing delta in rust (high performance alternative to spark or scala).
i. Tool first: 😢
Delta-rstas a tool for writing Delta table format in Rust
ii. Action first, tool second: 🚀
Writing Delta tables in Rust using
Delta-rst
iii. Hook, action, tool: 🦾
Delta tables without Spark! Using Rust with
Delta-rst
💡 In general, the tool and framework should not be the emphasis of your title.
3. Title Length
Not too long.
💡 You want your title to be visible on a search engine.
Read more here: Influencing your title links in search results
II. What is a good Subtitle?
💡 Subtitles share similar components as titles — they both act as an index for your reader, albeit subtitles being a secondary index.
What makes a subtitle good?
A good subtitle gives you a slightly higher resolution as the title, without repeating things.
Also follow SEO principles: Control your snippets in search results
4. Subtitles as higher resolution without repetition
Expand on the information in the title — or add more context or tone. And don’t repeat yourself. (Though do insert relevant keywords for SEO.)
Example: Subtitle without repetition
Using David’s article as an example again.
i. With Repetition
Apache Kafka, Flink, and Druid: A Popular Real-Time Data Architecture
Kafka, Flink, and Druid together create a rock solid, scalable architecture for real-time data applications. Even though they’re different Apache projects, they were all built for streaming data — it’s like they’re family.
This is a really clever subtitle! However, it’s too long. You want something which will fit in the subheader of a google search result. Consider extracting what’s not in the headline.
ii. Without Repetition
Apache Kafka, Flink, and Druid: A Popular Real-Time Data Architecture
Building a scalable architecture for real-time data applications with a family of Apache open source tools.
Much neater.
Example: Subtitle with higher resolution
Using Cynthia’s article as an example again.
i. Repetitive + not higher resolution 😢
How To Write a Subtitle That Makes Your Headline Shine
Write a good headline is as important as writing a good subtitle
ii. Repetitive + yes higher resolution 🚀
How To Write a Subtitle That Makes Your Headline Shine
A good headline can be bolstered by a good subtitle
iii. Not repetitive + yes higher resolution 🦾
How To Write a Subtitle That Makes Your Headline Shine
A great subtitle is half the battle — and this is your ultimate guide to winning it
5. Subtitle Length
This should be 1 sentence max. (Think, it should fit under the headline of a Google Search Result.)
Example: Shortening a Subtitle
Let’s use Rui’s article as an example:
i. Subtitle too long:
What is Medallion Architecture and How Can You Use It in Fabric?
Let’s explore the Medallion Architecture. An approach to organizing data that many businesses are using. We’ll look at how the Fabric platform can use this method and why it might be a great solution for managing your data more efficiently.
ii. Shortened Subtitle:
What is Medallion Architecture and How Can You Use It in Fabric?Organizing data in Microsoft Fabric with Medallion Architecture
Some insight into the literary craft of this subtitle:
- Verb (action) at the beginning
- Corresponds with “key” noun (data in Microsoft Fabric)
- Context at the end (Medallion Architecture)
- Keywords (SEO) in the center
- Human index →
organize data+msoft fabric
6. Titles and Subtitles in SEO
Titles and subtitles help people identify the content of your article. they also help search engines.
This deserves its own article, so I’ll just mention Google’s documentation: https://developers.google.com/search/docs/appearance
Conclusion
In summary, a good title should compell your reader without misleading them by providing descriptive information, and some element of tone. Subtitles provide higher resolution to the title, without repeating things.
Technical Writing Guide Series:
This article is part of a series on technical writing best practices.
- Emphasizing Personal Experiences with Callouts
Draw attention to your personal experience without disrupting the flow of your narrative - Technical Writing Guide: Adding Links
If something is important, link it!
