How I want you to write¶

I'm gonna write something technical.

It's often less about the nitty-gritty details of the tech stuff and more about learning something new or getting a solution handed to me on a silver platter.

Look, when I read, I want something out of it. So when I write, I gotta remember that my readers want something too. This whole piece? It's about cluing in anyone who writes for me, or wants me to write for them, on how I see this whole writing product thing.

I'm gonna lay out a checklist of stuff I'd like to have. It'll make the whole writing gig a bit smoother, you know?

Crafting Compelling Titles¶

I often come across titles like "How to do X with Y,Z technology." These don't excite me because X or Y are usually unfamiliar unless they're already well-known. Its rarely the dream to use X unless X is the dream.

My dream isn’t to use instructor, its to do something valueble with the data it extracts

An effective title should:

Evoke an emotional response
Highlight someone's goal
Offer a dream or aspiration
Challenge or comment on a belief
Address someone's problems

I believe it's more impactful to write about specific problems. If this approach works, you can replicate it across various scenarios rather than staying too general.

Time management for everyone can be a 15$ ebook
Time management for executives is a 2000$ workshop

Aim for titles that answer questions you think everyone is asking, or address thoughts people have but can't quite articulate.

Instead of "How I do something" or "How to do something," frame it from the reader's perspective with "How you can do something." This makes the title more engaging. Just make sure the difference is advisory if the content is subjective. “How I made a million dollars” might be more reasonable than “How to make a million dollars” since you are the subject and the goal might be to share your story in hopes of helping others.

This approach ultimately trains the reader to have a stronger emotional connection to your content.

"How I do X"
"How You Can do X"

Between these two titles, it's obvious which one resonates more emotionally.

You can take it further by adding specific conditions. For instance, you could target a particular audience or set a timeframe:

How to set up Braintrust
How to set up Braintrust in 5 minutes

NO adjectiives¶

I want you to almost always avoid adjectives and try to use evidence instead. Instead of saying "production ready," you can write something like "scaling this to 100 servers or 1 million documents per second." Numbers like that will tell you exactly what the specificity of your product is. If you have to use adjectives rather than evidence, you are probably making something up.

There's no reason to say something like "blazingly fast" unless those things are already known phrases.

Instead, say "200 times faster" or "30% faster." A 30% improvement in recommendation system speed is insane.

There's a 200 times performance improvement because we went from one programming language to another. It's just something that's a little bit more expected and understandable.

Another test that I really like using recently is tracking whether or not the statements you make can be:

Visualized
Proven false
Said only by you

If you can nail all three, the claim you make will be more likely to resonate with an audience because only you can say it.

Earlier this year, I had an example where I embedded all of Wikipedia in 17 minutes with 20 bucks, and it got half a million views. All we posted was a video of me kicking off the job, and then you can see all the log lines go through. You see the number of containers go from 1 out of 50 to 50 out of 50.

It was easy to visualize and could have been proven false by being unreproducible. Lastly, Modal is the only company that could do that in such an effortless way, which made it unique.

Strong Introduction¶

So, if you end up doing any kind of sales, you'll realize that.

What you actually need to understand is not what you have to offer as the product, but the size of the pain that the prospect is going through.

There are going to be readers that are just kind of curious and bored. They're not really going to be the ones that care about the product itself unless you can contextualize the pain for them.
It's really important to have an introduction that contextualizes the pain and foreshadows the solution.

If we can build that trust and I can correctly describe the pain that you are going through, then you will believe me when I am predicting the pain that you may also go through in the future. Ultimately, that is how you become a leader in the space—by demonstrating your ability to be right consistently.

The next time you publish or write something, they will believe it, and they will believe that they get value from it.

Strong Hooks¶

In the same sense that a title should often try to change the "how I" to a "how you" by eliciting an emotional response, the introduction can also help select the reader into a group that is feeling the pain.

This is the same reason why a plumber will have an introduction that says, "Do you have a leaky faucet? Call 1-800-PLUMBERS." That's a much more selective hook than just "I'm the best plumber in town." You can say that to everybody, whereas if someone answers the question of whether they have a leaky faucet, it automatically selects them to be a part of their readership.

I truly believe if you try to build a product too soon for everybody, you're gonna end up in a bad place.

Foreshadow Content¶

Once you hook them, you still have to first retain them. You can do that by foreshadowing the content you'll cover and even hinting at the reward.

For example, an introduction could look like the following:

If you're making $10,000 a month consulting right now, my goal at the end of this blog post is to help you increase your prices by:
- Asking the right questions so you understand the value of the solution you're offering.
- Providing tips on writing proposals and offering different options you can let your customer pay you more.
- Lastly, sharing some anecdotes with you on how I became more comfortable with charging two or three times more than I did when I started

Here, I've pre-qualified the reader for a certain range and told them what their goal is by the end of the post.

Two things are just the tips and the questions I'm going to suggest, and then the final reward is something a little bit more personal. Ideally, they read the first two knowing that my personal stories are coming after. That intro itself outlines the entire post.

Use Lists¶

Once you've hooked your audience, you have to retain them and reward them.

You'll also see that as part of the foreshadowing content, I've listed three items that I want them to take away. I can also be specific with the number of questions and the number of tips I'm providing.

By using lists and counting things, I can give them a notion of progress towards the final conclusion. If I'm on the second part, I know where I am in the story. The list itself allows us to break down the body and give the reader a sense of position. Since they know where they are, they know where they're going to be.

Demonstrate being an Oracle¶

One thing that's also really valuable to call out is the fact that you want to be seen as a leader or an oracle to this audience.

For example, if we go back to this charging more case, it's one thing to demonstrate that you understand that the reader's dream is to be able to charge more. It's useful that you're giving them a couple of tips and stories. But what can be even more powerful is to simultaneously:

Demonstrate your knowledge of the current problem.
Predict future problems as they come.
Foreshadow or reference those future issues in later content.

For example, the things you do to go from $10,000 to $30,000 a month are very different from what you would need to do to get to $200,000 a month. They require things like hiring, prioritizing your services, and improving distribution. If you can foreshadow that and call that out, when your audience gets to those levels, there's a chance they will remember what you said.

They'll think, "Wow, Jason was not only right about where I was but also where I was going." This brings a tremendous sense of trust and value.

It's not just this idea of future work or future considerations of the current work, but actually being able to predict the problems they're going to have in the future and suggesting that you are also the solution to those problems. You can foreshadow that as part of a series or whatever, but the general idea remains.

Have a Strong CTA¶

You also have to think about what the reward for yourself is. Ultimately, you should be writing this because you think the message is important and that you believe your audience should and deserves to get this message. The content of this post delivers the reward to those who stay and finish the article.

But at the end, you also have to get something in return. You should ask your user to do something. If it's a tweet, a simple one could be a repost, a like, or a share. It could even be a follow. It could be entering some GitHub link and giving the repost a star, etc.

What I realized to be very important was to make sure you only ask for one thing and don't split the attention. If you do that, you can have solid metrics on how you phrase CTAs and how that converts to certain content. For example:

How many people from the tweet go to the blog post?
How many go from the blog post to a subscription to a newsletter?

The more I think about it, the more I believe that most people should be capturing information into a newsletter rather than just Twitter. A direct email is so much more powerful.

No matter what it is, make sure you only ask for one thing. Sometimes it's to sign up, sometimes it's to try a one-click deploy. But if there's no action that your users can take, you've definitely made a mistake.

It's also good to call out that taking the action should have some kind of outcome as well.

If you want to see more of this content, follow me because I post twice a week.
That would be an example that I can qualify as a user and set expectations on what the outcome is.
If you like it, then subscribe. You'll get two posts a week.

I also think in many situations we should have tiers of qualified CTUs.

If you want to split your traffic, you should have an obvious condition as to which one someone should take. For example, on Indexify:

If you're dealing with terabyte-scale datasets, contact us.
If you want to try the Open Source library

It sets a prequalifier.

The terabyte-scale dataset is an evidence-based pre-filter. It could have said "in production," but something so specific like a terabyte or a terabyte a day really qualifies who should contact indexify