Almost a year ago I decided to give the paid subscriptions a go, not because I thought I could make technical writing my day job - I already have like three of those, and I can't imagine not doing any of them. It was mostly for validation: to see if I could get anyone to care enough about my writing to be willing to pay something, not a lot, for it. And also, it couldn't hurt, right?

Long story short, it worked... somewhat. In terms of validation, I'm more than happy for my 68 paid subscribers. I couldn't imagine even a single person would be willing to support my writing. That bit of extra energy also helped motivate me to write more, and, I hope, a bit better.

However, in terms of affordability, technical writing still is, for me and probably for the 95% of my fellow writers at The Tech Writers Stack, little more than a hobby. And sometimes a rather expensive hobby. Many of you have deep expertise in areas where you could charge a substantial amount by the hour, and yet you choose to share that expertise for free.

And I get it, believe me. I also struggle with the dichotomy of wanting to share as much as possible to the widest audience I can with the reality of having too little time and too much work—like, real work, the one that pays the bill—to be able to give my Substack all the love I'd like to pour into it. So, over the past year I've tried different models to strike the right balance for doing something that I love—sharing some hard-earned lessons on sometimes pretty complex topics—in a way I can afford to.

On one extreme, I tried doing exclusive articles, but I found out some of my best writing was hiding in plain sight from the vast majority of my readers. Why write exclusively for 68 people when other 2000 are eager to read it? On the other extreme, I tried the patron-like support-me-if-you-can model, but of course, the vast majority of readers can't afford to support you, even if they wanted to. And to top it all, the subscription model seems to be on the decline—I know I have subscription fatigue, and probably you too.

But now I think I've found a sweet spot, and I want to tell you about it because I honestly think if it works for me, it'll work for many of you, probably even better than for me. The gist is this: write a technical book alongside your Substack, using free articles as the main material for content and the medium to drive sales.

How it works

Here is (just one way) how to do it. Pick a topic that you're reasonably knowledgeable and you think you'd enjoy writing consistently about. As an example, graph theory is one of those topics for me. Aim to write between 2 and 4 articles a month on that topic. Each article is published for free in your Substack and becomes a new chapter (or part of a larger chapter) in your in-progress book.

Now, here's the part no one tells you (or at least no one told me!) You don't have to wait for the book to be complete to sell it. On the contrary, set up a Gumroad account from day zero, and start pitching the book on each of your free articles.

And yes, some people will buy that crappy version 0.1, assuming it's an interesting topic! To sweeten the deal, I set a fairly low “early access” price compared to what a full technical book might cost. And I also offer other perks, such as a private Discord for early readers, a special shout-out in the acknowledgment section, stuff like that.

But mostly, the selling point is just the fact I'm writing this thing in public, incorporating early feedback. That, and the fact your readers are amazing and will do everything they can to support you. And this gives them something concrete, a one-time transaction that doesn't trigger our dread for another subscription.

It's so simple that it seems it can't work, but my early experiments say it works one order of magnitude better than paid subscriptions. Of course, your mileage may vary, but I've seen in little more than a month almost the same net profit from early book sales than a year of paid subscriptions.

I've completely changed my Substack business model in the last month. No more paywalled articles. With this model, I've been able to make all my content open and free, and still have something valuable enough that some readers are willing to pay for.

I still have subscriptions enabled on my Substack, though they have now become a free-ride ticket to all my current and future books. Readers who want to support all of my work, and can afford to, will still go for a traditional subscription. But those who can’t or simply don’t want to be attached to yet another subscription, have this alternative. It's a win-win

And besides all the advantages in terms of profitability, there's another way in which this pivot has positively impacted my writing and it's even more important: I'm more motivated than ever to write. Since all my writing is now public, I know I'll have as many eyes as I could wish for every article. And at the same time, I know I'm not writing exactly for free. Each article brings a trickle of new book sales, not enough to make a living out of it (yet) but enough to trick my primate dopamine-seeking brain.

But, but…

"But wait—I hear you ask—writing a book is supposed to be very hard!"

Yes, it is. It is harder than just writing a sequence of more or less interconnected articles. There is definitely extra work involved in writing, formatting, and setting up yet another platform (because why the hell Substack doesn't have that feature yet, right?).

But here is the thing. Writing is way harder than any of that, and you're already doing the bulk of it. The rest is not that much harder. If you can consistently pump one article every couple of weeks, believe me, you can write a technical book.

"Ok but, what if I don't write about a single, focused topic?"

I hear you, I'm writing not one but three distinct books on very different topics and for different audiences because I have many diverging interests. Perhaps you can find a subset of your articles that can be tied together into a coherent topic, like I did. Or perhaps variety is your thing! Maybe your book is about 20 weird, interesting things few people know (I’m looking at all you polymaths out there!)

"But—I hear you again—I just want to share my knowledge freely!"

I get it, and it's commendable, truly. If you can afford to, that is. But what I've found out is that more often than not even those who already are in a very stable financial position, eventually discover they can't write for free as much as they'd want to. There is a finite amount of time and so many things to do with it.

This is a way to make that free writing at least a bit self-supporting. But you can still make 100% of your content free. That's what I'm doing with my graphs book. Everything, including source code, is available for free online. The book is just a convenient packaging with some additional syrup and a couple of cherries on the top—if you can pardon the lousy metaphor.

The point is that you can adapt this model to your interests and values. You can make all or most of the content free, or you can make the book an extended version of your articles. The core of the idea is that 80% or more of the work is already done when you hit publish on Substack. And the remaining 20% could be enough to make the whole thing, if not profitable, at least affordable.

Some final words

Listen, I'm advocating strongly for this business model because I'm rooting for you. I truly believe the vast majority of you technical writers out there have what it takes to make a compelling book on your area of expertise. But I understand this is not for everyone. So here are some reasons why you might not want to do this.

First, it does take some extra effort. The hardest part is, as you might suspect, consistent writing. I waited for more than a year to make sure I'd found the workflow and rhythm that allowed to me write more or less consistently without the rest of my world breaking apart. If you're only a couple of months into technical writing, maybe it's better to wait until you've found your pace.

Second, it does put some extra pressure on you. Once you commit to a topic, you'll have to find a way to stay motivated to write about that same topic for over a year--or as long as it takes to finish the book. You can take some rest here and there, of course. But once you have people paying in advance for something you'll deliver in the near future, some pressure will inevitably build up.

And finally, we all know once a hobby becomes a job, it stops being fun. And there is the risk this model turns your otherwise pleasurable moments of exploration into yet another thing you have to do, instead of a thing you want to do. I don't have any magic potions to fight that, but I've found keeping a healthy variety of topics to write about lets me procrastinate from one while investing in another topic, tricking my primate brain into thinking this is not work.

But all in all, I think this is one of the most underrated business models for technical writers, and there has never been a better time to do it. You have the technology, the platform, and now a community of like-minded writers to support you and help you stay motivated, and sometimes kick you in the butt if we must. Please go ahead and give this idea at least a fair chance, you'd be surprised how much you can enjoy it.

And if you are interested in actually doing this, we at The Tech Writers Stack are building a community of writers to help each other. We proofread each other's works and share tricks and tools, and some of us have become full-time collaborators. Join us now and let's kickstart your indie tech writing career together.

Join The Tech Writers Stack

PS: If there is enough interest, I'm happy to share a few more technical articles on my actual process, from the tools I use to the workflows I follow. Leave a comment if that sounds enticing to you.

Leave a comment

Mastering the art of revising technical documents can be challenging, as most writers dread the revision phase. It's thrilling to let your thoughts flow onto paper, but revisiting your work to correct inconsistencies and errors can feel like a chore rather than a creative exercise.

Many technical writers struggle with revisions for two main reasons. First, it's difficult to balance generating new ideas while simultaneously critiquing your writing. Second, many writers revise their work in an unstructured and unfocused manner, often by simply rereading and making changes until nothing else seems wrong. This approach is far from ideal.

In this article, I'll introduce a more effective revision method that works for me and many successful writers across various genres. Adapted from prolific fantasy author Brandon Sanderson, this technique is applicable to fiction, technical documents, and textbooks alike.

The method revolves around two key principles: decoupling writing from revision and revising with intention.

Principles of effective revisions

By separating the writing and revision processes, you can enter distinct mindsets for each task. This allows you to focus on creativity while writing and critical analysis during the revision phase. When revising with intention, you avoid simply correcting errors as you encounter them. Instead, develop a structured plan that addresses specific issues in your document. Following these principles can help transform the revision process into a more enjoyable and efficient experience for any writer.

Decouple writing from revision

Think of yourself as either the creator or the critic, but not both at the same time.

When in creator mode, focus on writing whatever comes to your mind. Some writers are more structured and prefer a clear outline, while others are less structured and like to let their thoughts flow freely onto the page. Regardless of your approach, when writing, just write. Don't revise or reread what you've written – simply create.

Once you have your first draft, switch to critic mode, but take a break before revising it. It can be a short walk, making coffee, or watching a YouTube video. Or just sleep over it for a couple nights. Give your mind some time to reset from the writing process.

When you’re on critic mode, your goal is to analyze and improve your work. Tackle revisions one step at a time – don't try to fix everything at once. Instead, focus on specific aspects during each revision phase. We will expand on this idea next.

In critic mode, don't make any changes to the document. Instead, go line by line and make comments on sections, highlighting sentences or words that need improvement. There is some nuance here: you can fix minor issues like typos or missing commas –most writing software will catch these errors anyway–, but don’t fix anything that takes, say, more than five seconds of thought. Instead, just leave notes.

After finishing revising the document, take another break to clear your mind. Later, return in creator mode to address the revisions. Although you should focus on fixing the identified problems, don't feel restricted by them. You can disagree with the revision or add new sections inspired by your critique.

Remember to allow yourself creative freedom while addressing the revisions, as this will help improve your writing overall. Perhaps add a dash of excitement and consider differing slightly from the critic's viewpoint. Treat the critic not as a commanding boss, but as a helpful editor offering suggestions to enhance your work.

Now you get the picture, right? Enter creator mode, make adjustments, and then allow your text to rest before revisiting it for further revisions. Continue this back-and-forth until you're pleased with the results. By separating these two roles and being mindful of your objectives during each stage, you'll create a more efficient revision process that allows you to make the most of your writing and editing sessions.

Revise with intentions

Tackle each revision with a concrete plan of what issues to look for.

When revising a document, you may face various issues, from missing commas and weak verbs to unsupported conclusions and major structural problems. Revising with intention means separating your concerns and addressing them from high-level to low-level problems.

First, focus on the document's structure. Is your main claim clear? Do each section and part support that objective? Is the order of arguments and ideas correct? Should anything be explained earlier? Does your conclusion tie everything together, or is it scattered? Is there a strong introduction with a motivating problem or example? Consider the story your writing conveys and assess its coherence, flow, and organization.

Next, address low-level concerns like engagement and clarity. Choose the best words and synonyms to convey your message. Select strong, clear verbs that communicate your intentions effectively. Are you using a passive voice, or is your writing active and engaging?

Mid-level problems involve paragraph structure and clarity. Make sure each paragraph supports your argument effectively and clearly. Can you rearrange the order or words to improve clarity? Consider moving the premise to the beginning and the conclusion to the end.

You can divide the editing process into multiple stages. A simple approach is two stages: one for structure and one for content. For short articles, start by reviewing the overall structure and flow of ideas. Then, thoroughly revise the content to ensure appropriate synonyms, words, verbs, voice, and sentence structure. This is what I do with most of my blog articles.

You can also split it into three phases: 1) high-level story structure, 2) clarity of ideas, and 3) engagement. First address the high-level story, then focus on each argument's explanation and consider adding examples or reordering explanations for better support. Finally, review engagement by examining verb strength, active sentences, and meaningful word choices. This is what I do with longer articles, such as book chapters or scientific papers.

Now, here is the important part. When entering critic mode for revisions, clearly state which phase you're in and focus on detecting specific issues. Before starting the revision process, state your objective and identify the issues you're looking for. Write down general questions that address these problems, such as: Is the structure's order correct? Is the tone active and engaging? Are all verbs strong and meaningful?

As you revise, refer back to these questions and assess the text based on them. When providing criticism, avoid simply saying something is wrong. Instead, explain why it's wrong: The structure isn't right, it's not easily understood, or it doesn't address the claim being made. Be detailed in your critical revision.

However, don't suggest solutions at this stage. Just criticize. Point out if the tone is too casual or formal, if a verb is weak, or if an argument lacks evidence. Leave a focused set of comments for your next creative phase.

Final remarks

Let's end by discussing some caveats to the principles we mentioned earlier. First, the principles themselves are more important than their strict implementation. The key ideas are that you should either be writing or revising, but not both at the same time, and that you should have a clear idea of the issues you're looking for when revising, instead of looking all over the place.

You don't need to be extremely structured with your schedule; some people prefer a looser approach. The important thing is to keep these principles in mind when working on your document.

When revising, take notes and write them down. One common issue with revision is making mental notes of problems and then trying to fix them without writing them down. Instead, put yourself in the shoes of someone who isn't the author and leave thorough notes about the document. Don't overthink these comments – they're for yourself, so focus on addressing one specific issue per note.

Lastly, how long should you revise? Ideally, you would continue until you're satisfied with your work. However, remember that perfection isn't always achievable; focus on creating clear and effective content while adhering to these principles.

For most, the “revise until satisfied" method doesn't work because you'll never be satisfied with your own work. So, what I do is set a fixed number of cycles, like two revisions—one high level and one low level—and then I publish.

Of course, you have some freedom when in creator mode.If you feel the high-level structure is okay during a revision, you can move to the next stage. Alternatively, you may leave a note for your next editing session to do another high-level revision pass. You have the freedom to do this, but working with constraints is important.

Tell yourself you have two or three revisions to fix it, and then hit publish. Otherwise, you may perfect your document forever without ever being satisfied.

Share

If you are a technical writer, chances are you have marketable knowledge that many readers would happily pay for. While Substack provides one compelling strategy to monetize this knowledge –paid subscriptions–not all readers can or even want to subscribe to yet another service.

In this article, we'll explore different strategies for making money with your technical writing skills beyond the subscription model. First, we'll look at the most common monetization method that works well with Substack: paid subscriptions. Then, we'll discuss alternative strategies that may not be as easy to implement on the platform but can still be effective with some workarounds.

Strategy #1: Subscriptions

This is the fundamental monetization model on Substack. The idea is that readers pay a monthly or yearly subscription to access your content. This approach is appealing because it provides a steady income, and you know how many people you're writing for at all times. Plus, it's scalable – the same effort and quality of content can reach as many readers as you can attract.

However, one downside is that it can lead to burnout since you might feel pressured to produce content for your subscribers constantly. At the same time, many people are getting subscription fatigue, as the Internet all around us has become a giant subscription model. Plus, readers won’t necessarily care about everything you write. Yet, with a subscription, they commit to reading (or at least paying for) all your content.

Strategy #2: Pay-per-article

Instead of paid subscriptions, consider charging an access fee for individual articles. Readers can preview the beginning of the article and choose to unlock it for a small one-time fee, perhaps as low as $1.

Unfortunately, Substack doesn't currently support this feature, likely due to the small amount of money involved per user after deducting fees. Implementing this would require them to hold to your money and send payouts whenever you reach a significant sum, which complicates matters financially for them, so I don’t see them doing it anytime soon, unfortunately.

But don't worry; you can still implement this strategy using other platforms like Gumroad. To make this work with Gumroad or a similar service, you must create a product for each paid article. The content of the product is simply the secret drat link (that you can find in each article settings page). Then, in the actual article at Substack, just before the paywall, include a custom button linking to your corresponding product checkout page.

This way, you can still benefit from Substack's reach while utilizing alternative monetization methods that suit your needs better. This strategy lets you monetize at a finer level, attracting those who might not want a full subscription but would pay for a specific article. However, it does require managing multiple platforms since it's not integrated into Substack.

You can combine this with a traditional subscription model, allowing regular subscribers to receive everything while others can unlock individual articles. Make sure the total cost of paywalled articles is similar to or greater than a yearly subscription; otherwise, subscribing won't make sense.

Strategy #3: Lifetime subscription

The third strategy is offering a one-time payment for a lifetime subscription. For example, charge two or three times the yearly subscription cost for unlimited access to your content forever.

Many readers experience subscription fatigue and prefer paying a larger amount upfront instead of dealing with recurring payments. The downside is that it requires more money upfront from readers, but some may be willing to do this.

Why this makes sense? It depends on the lifetime value of your readers. Substack and other subscription services have a churn rate – a percentage of paid readers who don't renew their subscriptions. If you’ve been on Substack for long enough, you can calculate an average churn time, but it is usually around two to three years for technical publications.

So, if you charge upfront for lifetime access, you might earn the same or even more than you would from readers who only subscribe for one or two years anyway. For a two-year or three-year rate, you receive the total value of the subscriber upfront.

Substack doesn’t natively support this feature, so you’ll have to do manual work, i.e., comping the corresponding readers forever. Now, you can, of course, set this up with Gumroad, Patreon, or any other platform, but you can also use Substack alone by taking advantage of a less-known feature: the founder’s plan.

To do this in Substack, set up a founder's plan alongside your yearly plan. Make the founder's plan, e.g., three times the yearly rate, and clearly state in the description that it's a one-time payment for a lifetime subscription. Ensure this is clear in your about page, plan benefits, and settings.

When someone purchases the founder's plan, you'll receive an email. You'll need to manually give them a complimentary subscription forever by going to your subscriber's page. Although this requires manual work, it's not a huge burden since you won't receive many such emails daily.

And if you're getting dozens of lifetime subscriptions a day at more than $100 each, that's a great problem to have! You can even hire someone to handle this task.

Strategy #4: Sell digital products

Strategy number four involves monetizing something other than your articles. For example, if you write technical articles or tutorials for a programming language and you have written (or are writing) a technical book, you can use your articles as a free gateway to promote it. Include a link to your Amazon or LeanPub page under all your articles.

You can apply this strategy to finished products, like promoting a complete Python programming book alongside your technical tutorials. Alternatively, you can use it like a Kickstarter campaign. Ask readers to pay a small pre-order fee upfront and let them know they'll receive frequent updates and the full content when the book is completed.

For example, whenever I write a new chapter of my upcoming CS book, I send supporters an updated PDF and EPUB file. This method provides very-needed seed funding for a big project, such as writing a technical book. Again, you can use alternative platforms like Gumroad, Patreon, BuyMeACoffee, or simply provide your PayPal link.

Strategy #5: VIP access

Another way you can monetize your technical blog is by providing paid readers with exclusive access to a community. For example, you could say that all subscribers can read your articles, but paid subscribers can access a Discord server to ask questions, get feedback, and work through problems with your help. You can also use this community to host live workshops or other face-to-face events that offer additional value to paid readers.

This way, everyone can read your content, which helps you grow your reader base, but only paid subscribers receive this extra support from you through office hours or personalized assistance.

Similarly, you could offer additional content to these paid subscribers. For example, while the article may have text explanations and snippets, subscribers could get access to a private GitHub project with the actual source code they can run. This way, you can monetize extra content that's appealing to some readers without taking away the value of the free article for most of your audience.

Conclusions

Substack is a fantastic platform that provides valuable tools to make a business around your writing, if you choose to do so. However, the paid subscription business model is just one of many possibilities to monetize your hard-earned knowledge, time, and effort.

While Substack doesn’t natively support any alternative revenue model, you can, with some work, integrate other platforms –or even manage things fully manually– to accommodate other revenue models that may complement paid subscriptions or replace them altogether.

As Substack matures and grows, I expect its founders to realize there are many alternative models they could support natively. In the meantime, you can use some of the tricks in this article to make one of these models work for you.

Now is your time to share! Do you have any other tricks or ideas to monetize your technical writing?

Leave a comment

What is the right way to do Substack?

There is an ongoing debate over notes and posts in general, with what seems to be two camps at Substack debating the right way to approach writing on the platform. I call them the pragmatists and the purists —no offense intended with either label. Both sides have compelling reasons to claim their way is the right way.

So, I guess it’s my time to pick a side, right? Well, not exactly. I will share my thoughts on this debate, but keep in mind that my perspective is influenced by my own experiences and motivations, which may not apply to everyone. So here are my two very biased cents.

Pragmatists believe that success on Substack, defined by having many readers and making it profitable, requires giving readers what they want. This often involves choosing a niche, maintaining a consistent schedule, addressing readers' interests, and aligning with a specific mindset or echo chamber. To stand out in the competition, you must write well and create content people want to read. Essentially, this camp suggests optimizing your writing for your audience, treating it like a product designed for a target market.

This is the writing as a business side.

On the other hand, purists argue against this approach, claiming it leads to burnout and misery. They believe that writers should focus on what they truly want to write about and follow their own schedules. This might mean writing five essays in a week or one essay in a month. Eventually, if your writing is genuine and good, readers will come; more than readers, they will be friends.

This is the writing as a calling side.

I think the right way to do Substack is… anything in between. And yes, I know, this is the blandest opinion I could have. But hear me out. I think I have a point to make.

The two extremes, writing as a product and writing as an art, are both valid. The fake dilemma arises when you ask the wrong questions first. Instead of asking what to write about or how to write, start by asking why you're writing. That is, determine your motivations first: for income, curiosity, self-discovery, finding peace, or building a community. Once you know why you're writing, choosing topics, schedule, structure, and niche becomes much easier.

If you want to make a living from your writing and create a business, you must write about topics people will pay to read. In this case, your work may lean towards news digests, explainers, or something more product-oriented.

On the other hand, if your reasons for writing are more personal – connecting with yourself or a community, finding your voice, understanding your emotions, or satisfying your curiosity – then your writing will feel more personal and chaotic, connected to those pursuits.

Now, once you find a why and a what, how is more or less pretty straightforward, good writing advice works across all genres – be it fiction, news, essays, or a scientific paper. Your writing should be engaging and strong, reflect your values, and encourage the reader to ask difficult questions.

You should strive for good, clear, straightforward writing that doesn’t make the reader struggle to understand what you mean. This will always improve your writing, whatever your motivations or topics. Likewise, using personal stories, relating to the reader's experiences, and having a strong voice all contribute to engaging and compelling writing.

Some aspects of the "how" will depend on the "why." For instance, a consistent schedule and structure are more important if you're writing for money because you're creating a product. On the other hand, if you're writing for artistic or personal reasons, having a schedule or consistent structure is less crucial. Instead, it's essential that each piece feels unique and genuine. But most writing advice is general.

So there you go, there is no real dilemma. This discussion might seem like a dichotomy because people disagree on the "why." If you and I are writing for different reasons, it's natural that we'll write about different topics using different techniques.

And here's my strong claim of the day: all motivations for writing are equally valid. No one can tell you why you should write or what motivates you to become a writer. There are no stupid reasons to write.

Why are you writing on Substack? That's something only you can answer. No one else can judge your motivations, no one is on your shoes. Once you know your reason for writing, then we can talk about whether your actions align with those motivations and see if there’s something you could do better. But the why, that’s all on you.

So here is my question for you: why are you writing?

A previous version of this post was first published early last year. This is a revised and slightly extended version that came out of several insightful comments and discussions on the original post.

We’ve all been there. You wrote the perfect blog post for solving that painful problem elegantly. Your readers should be delighted; there’s everything they might want to know. And yet, hardly anyone reads the whole thing. If only they gave the article a chance, they would find out how incredibly useful it is, right? But you find it almost impossible to get readers interested long enough to discover it themselves. Sounds familiar?

I’ve struggled with this issue for years. I’ve written solid papers that reviewers didn’t grok. I’ve given insightful lectures that put listeners to sleep. I’ve pitched exciting business ideas that landed flat in the face of potential investors. I’ve tried every trick to hook the audience, and most don’t work. But I’ve found a remarkably simple strategy that does work.

Convincing your readers about the importance of some topic is the hardest part of technical writing. Doing the research, finding reputable sources, and actually writing and editing is devilishly complex. But it’s nothing compared to getting your readers to care. Ask any technical writer, and they will all tell you the same: it doesn’t matter how good your content is; most people won’t stay long enough to find out. They’ll give you the benefit of a couple of minutes, at most, and decide their time is better spent elsewhere.

Why is this so hard? You are dealing with the quintessential problem of communication: how to hook your audience so they’ll stick long enough to allow you to deliver on that hook? The problem starts with human psychology. You see, we have evolved to prioritize. Things potentially dangerous or that satisfy our basic instincts hijack your brain —that’s how social media keeps you hooked.

What happens is that you’re trying to sell the reader a solution to a problem they don’t care about. It doesn’t matter how elegant, effective, or simple the solution is. If your reader is not invested in the problem, you're preaching to the void. Thus, you must convince the reader that your problem matters to them first, and only then can you show them the answer. Start with Why.

Let’s break it down.

Start with Why

Engagement begins with the Why. Your aim here is to establish three points: the importance, complexity, and solvability of the problem.

Regarding importance, your job is to convince your reader that the problem is relevant and significant to them. You do this by highlighting all the negative consequences of not solving that problem. It could be framed as an undesirable world state your reader wishes to improve or a negative consequence of not taking action.

Then you tackle complexity. You should debunk common but ineffective solutions, showing why they fail to solve the problem, or at least how they fail to solve it in the way that matters in this case. This doesn’t need to be a detailed explanation, but at least show that you’ve done your homework and know the problem isn’t trivial.

Finally, you can introduce the critical insight that supports your solution as a better alternative. The trick is not to spill the beans just yet, but instead say something that hints at the solution, and, ideally, makes something click in the reader's mind. In this post, that insight is the idea that we have evolved to prioritize things we believe are essential.

Punch with What

Next comes the What, a concise statement. The purpose of this claim is to get stuck in your reader’s mind.

Keep it simple yet comprehensive for easy understanding. If they take away anything at all from you, it should be this. So make it easy to remember: use mnemonics and put it in big, bold, centered letters.

To understand your what, consider the following two questions: “what is this article about?”, and “what does it say about it?” Most writers think the answer to the first question is what should stick. But that first answer is often just a promise, a high-level prompt, not an actual answer. You want to incept the second answer in your reader’s mind.

Let’s see in this post:

— What is this article about?

— The best way to structure your content to make it engaging.

— Oh, and what does it say about it?

— That you should answer the Why, What, and How, in that order.

See? That final answer is the What —the thing you want the reader to answer when prompted in detail.

Deliver with How

Finally, you get into the nitty-gritty of How. This is where you’ll spill all the beans, and provide a thorough explanation of the actual solution. At this point, the reader should be invested in the problem, and happily surprised by the hint to the solution that is your What. Now is the time to deliver.

For highly complex solutions, start with a top-down approach. Begin with an outline at a high level of abstraction and then detail the steps to implement the ideas. The purpose is to avoid overwhelming the reader with too many details before they grok the big picture.

An alternative approach is to start explaining the separate components of the solution from the bottom up and then tie them together at the end. This approach is more effective when the overall solution cannot be easily reduced to its parts. With enough time to understand in detail each part, the reader can hopefully see the overall solution emerge naturally.

Whatever approach you pick, remember to make it didactic. The goal is to teach a new skill, so the language and pacing should match the reader's expertise level. If it's too easy, it will be dull and uninteresting; and if it's too challenging, the reader won't learn anything at all.

Finding the right balance

The time apportioned to each of these parts can vary, but as a general rule, you should spend a fair amount of time in the Why, say, no less than 30% of the whole content. The What aspect usually requires the least time since it's an overview that can be displayed through diagrams or short headlines. Then, the How can take up all the remaining space. The exact balance will depend on the type of content and audience you're writing about.

For instructional and educational material, for example, you'll likely spend around 20-30% of your time setting up the problem's context and causes, 10% outlining what the solution is at a high level, and then devote 60-70% on detailed instructions for the solution. This is the typical distribution for a tutorial-like post here in Substack.

In contrast, if you’re preparing something short —e.g., a product pitch with a limited time— focus mainly on the Why. Nearly all your content should explain why an issue needs resolution and convince the audience that this is the most critical problem in their lives (at least while you’re talking). Then, you can briefly introduce your service, product, or idea as the answer and provide simple usage instructions as the How.

These are the two extremes; anything else likely falls in the middle. College courses, for example, are often designed with a combination of lectures and practical classes (or laboratories). In this case, the lecture can cover the Why and What, leaving much room to ensure students get invested in the problem. Then, the practical part takes over the How.

Closing remarks

If you’ve been paying attention, you’ll notice that this article is organized in this fashion. I spent a fair amount of time trying to convince you that engagement is a vital issue that you want to solve, then I pitched a simple high-level solution to you, and finally, I spilled the details. If you’ve read this far, then I’ve succeeded. And now you know the secret: Start with Why.

In this short post, I will highlight five hugely useful and reasonably easy-to-implement features for technical writers that would elevate Substack to the best online tool for our breed.

I will cover editing, organization, and monetization. Feel free to comment and add any suggestions you think would also be helpful for your writing workflows.

While I have zero leverage with Substack developers, I do hope this post gets in the eye of someone with the power to push for some of these changes. I think it would be a win-win.

#1 - Support for code syntax

This is a must for technical writers in the computer science and software engineering area. It is simply too cumbersome to share code today in Substack. Our best options are either the severely lacking native code block (which is just a monospace font) or embedding a GitHub Gist —or worse, an image.

On the other hand, this is so easy to implement that it is inconceivable that Substack still hasn’t solved it. There are dozens of fancy text editors with support for syntax highlight that could be included in Substack.

One argument I hear a lot is that Substack prioritizes the email experience, and email is very limited in what you can do with CSS. However, possible solutions involve either rendering an image version of the code, or falling back to a less fancy rendering on email with a generated link to the web version for those who want to see the code block in its full splendor.

#2 - Series with custom navigation

Many of us write a series of posts on a given topic. The usual way to organize them is to put something in the title (e.g., “Foundations of CS #1 - The actual title”) and/or to use a custom tag.

However, since there is no notion of an actual series, there is no built-in navigation. So, we have to manually add navigation links, which means we have to edit past posts to add forward navigation. The native navigation links work across your entire publication, so if you’re writing two series simultaneously, the links will get mangled.

An easy solution is for Substack to allow defining an arbitrary tag as a series, which would potentially add native back/forward navigation links among the series' articles. Also, one could optionally define that a given tag lists posts in increasing order (older to newer) instead of the default (newer first) when reading articles in chronological order makes sense.

#3 - Conditional sections

As a software engineer, one of the mantras I live for is DRY — Don’t Repeat Yourself. When writing a piece for non-, free, and paid subscribers, I have to consider how different readers will see my article and add pieces here and there that only make sense for some of them.

Conditional sections would allow us to mark some sections as free-only, paid-only, non-subscribed-only, etc. Right now, the only feature reasonable close is the paywall which basically divides the article into an intro that everyone sees and a full content that only paid subscribers see. However, there is no way to put something only for free subscribers, for example.

Ideally, I would want to make a section conditional on any of the filters they allow on the subscribers page. For example, I could make a section that only appears for first-time readers, or, on the contrary, for my 5-star readers.

#4 - Pay for single posts

This one is a bit harder because it probably messes with the business model that Substack consider optimal —the long term subscriber. While I do live my yearly subscribers, I also recognize that some readers won’t get a full subscription just to read one paywalled article that interests them.

The solution is, of course, to extend the payment mechanisms to allow us to charge for individual posts. Even better, give us a fully customizable tiered system where I can offer different things to different categories of subscribers, as complex as I want.

Right now, we only have three fixed tiers: free, paid, and founders. If I now want to offer, for example, a paid course, I have to either make it accessible to all paid subscribers or manage payment outside Substack. They are leaving a lot of money on the table for the lack of a more full-featured payment system.

5 - Global or category-based tags with search

I love tags, as they allow me to organize my articles in non-disjoint categories (as opposed to sections) and then link to the list of all relevant articles on a given topic by using a /t/ URL. However, unless you decide to put links to your tags, they are invisible to me as a reader. Furthermore, I’m sure several publications use similar tags (e.g., many of us have a programming tag or something similar).

What if, when adding a tag, Substack would suggest similar tags used around the community (category) I’m in so that later readers could find individual articles by tag on the Discover page?

Right now, for the most part, different substacks are different silos. Unless explicitly linked to them, navigating among similar publications or finding relevant articles related to what you just read is almost impossible. While going full automatic recommendation is something I understand they are cautious of —we’re all sick of the algorithms dictating what we consume— searchable tags can give writers and readers the power to find what they want transparently.

That’s it for today. These are just five relatively easy-to-implement features that I believe would elevate Substack to a different level altogether. As a software engineer, I understand that all features need to be balanced in terms of complexity versus the value they provide, but I truly believe these are absolutely worth it.

What do you think? Is there something obvious that Substack doesn’t provide and would make your writing so much easier?

If you read our previous article on a pragmatic workflow for incorporating generative AI into your writing, you’ll know we love AI, but we also believe the only genuine way to use it is by keeping the human at the center. If you haven’t read it, check it out; it’s pretty cool.

This post complements that article: we share three prompts we’ve been experimenting with lately to streamline this process even more.

We use these prompts as templates for Bearly.ai because it makes it extremely convenient to simply fill in some fields and hit a button, but you can use them directly with ChatGPT as well. We haven’t tried these with other LLMs so they might not work with Llama, Claude, or anyone else. If you do try them, we’d love to know!

Let’s go!

Proofreader

The first prompt acts as a proofreader. The most important feature of this prompt is that it makes the least possible number of changes to fix grammar, orthography, and punctuation. Thus, it tends to keep the same paragraph and sentence structure unless you have very long sentences. If your text is flawless, it will probably make no changes.

To use it, paste your paragraph, substituting the {{ input text }} fragment.

You are a proofreader. Your task is to rewrite the input text below to improve the grammar, orthography, and punctuation. Keep as much of the original text as possible, only rewrite where there is a mistake. Remove repeated words and split long sentences. Do not add any content that is not in the original text.

"{{ input text }}"

Editor

The second prompt is more flexible. It allows the model to rewrite the entire text to fit it into a new style and audience. So, always review the end result carefully, because it will change almost all your words, and probably reorder sentences as well.

In this prompt, you must also specify the tone —e.g., “formal”, “casual”, or even “slightly drunk with a bit of sadness”— and the audience —e.g., “little kids”, “professional computer scientists”, etc.

If the text is too long (like, several paragraphs) or too short (like a single sentence), this prompt can hallucinate and add its own content. However, we’ve seen when the text is one or two paragraphs, it tends to behave correctly. Do experiment with different text lengths.

You are an editor. Your task is to rewrite the text below to improve its style. Keep as much of the original content as possible, but rewrite sentences in active voice, and split the text into meaningful paragraphs. Consider the following tone: {{ tone }}. Assume the reader is {{ reader }}, and choose words appropriate to their level of comprehension. Do not add any content that is not in the original text below.

"{{ input text }}"

Structured Outline

The final prompt is different in that, instead of changing the wording, it generates complementary content in the form of an ordered list of short sentences. These are the main claims of your input text. We use this prompt to extract key insights from very messy audio transcripts, for example, so we can reorder, mix, and refine them before doing a second round of writing.

Again, it is sensible to the length of the input text. Too long or too short, it will tend to divagate or hallucinate, but it works pretty well with chunks of ~1000 words. If your text is longer, consider splitting it into sections.

Your task is to extract the main claims of the following text and create an structured outline. Identify the main claims made through-out the text, and summarize each in a single sentence, in active voice. Enumerate all the claims in the same order in which they appear in the original text. Answer only with the enumerated list of claims.

"{{ input text }}"

Needless to say, these prompts can fail spectacularly, so always double-check the output. They are meant to help you, not to substitute you. Do play with them, try some modifications, and let us know what works and what doesn’t.

Consider sharing this article with all your writer friends if you find it useful.

Share

This is a guest post by from . If you don’t know Andrew, give him a follow. He writes every single day about basically everything. For me, who can barely keep up with a bi-weekly post, that is insane! So I asked Andrew to spill the beans on this trade secrets, and boy did he deliver. Enjoy!

— Alejandro Piad Morffis, Editor at .

asked me to write something down about how I write. Pretty meta, right?

Why me? What’s so special about me, and why should anyone care what I have to say?

Well, I’ve written every single day for nearly 200 days in a row now, and I have no intention of slowing down any time soon. Is what I write any good? You’ll have to be the judge of that, but there’s no doubt I’m consistent and prolific.

If I’ve learned one thing for certain from my near-daily practice of Brazilian Jiu Jitsu for about 25 years, it’s that you get better by doing something every single day. This lifetime of discipline and near-obsession has carried over into my writing, which has evolved a great deal over the last 30 years or so.

My intention with this piece is not to get you writing every day, though—if that works for you, I’m here for it, and I’m excited for you—but writing every day isn’t possible for all of us. I’m cognizant of the privileged position I hold, and I mean to employ noblesse oblige by paying it forward to others.

My view is that growing the pie is better than trying to have a larger slice of said pie.

Mmmmm…. pie…

With all that said, I am excited to help you get better at writing! I don’t know everything, and not every idea will work for every person. If these ideas don’t help much, that’s okay—but there’s a good chance something in here will help you out a bit. Let’s dive in.

Idea Repository

Probably one of the most crucial elements to what I do every day is the idea repository. If you ignore everything else and add this, it will change things for you.

Ideas, for me, come easily. I’m a curious person, and I get excited about a lot of things. I enjoy sharing those things with my readers. However, the ideas are often fleeting. They last maybe 30 seconds, or maybe 30 minutes, and then they’re just gone. Poof!

Not every idea disappears, but more do than don’t, so every time I have an idea, no matter where I am, I write it down quickly. Writing on paper with a pen isn’t usually possible, but I almost always have my phone with me, and I can usually articulate something like a title or a very, very brief reminder of what I want to write about.

And… that’s it. I might get 5 ideas in a day, then nothing for a couple of days, but there’s almost always an average of more than one idea per day. That’s good, since I write every day. The trick, for me, is to write the idea down immediately, and then to keep all of these ideas in one document, preferably cloud-based, although I will frequently simply email myself the idea, then add it to the repository.

The Routine

So, I write every day. Why has this been possible, and how could it work for you?

I wake up pretty early nowadays, usually between 6 and 8 AM (okay, it’s early compared to most of the rest of my life!). I like to do this because I have the house to myself, or at least a nook of it. I need some “me time”, so I have this time carved out every day.

I begin writing after about 30 minutes of listening to news, brewing coffee, and reading a little bit. I always dive right in first thing, when my mind is at its sharpest—it’s warmed up now, but still very fresh, like a boxer coming out for round one with a little sweat going.

This is often the best part of my day! I am sharing something from inside my head with the rest of the world, and it’s pretty likely that someone intelligent will have some things to say about my observation. I love that interplay, and I get a lot smarter every day by interacting with folks in the comments (or via email).

Being excited and remembering why I’m doing this is important, but even more important is to turn this ritual into a routine. If you simply start writing every day (or however often you can) without having to plan for it—without having to move stuff around on your calendar or even physically moving stuff around—something will start to feel “off” if you don’t write.

That’s what you’re after.

Make it boring. Make it routine. The exciting part should be exploring the ideas and releasing them for folks to see, not amping yourself up to write, or making time for it, or anything else, really.

The Outline

You probably learned how to use an outline around middle or high school, so I don’t want to act as though I’ve discovered a new exoplanet or anything. At the same time, I don’t want to take for granted that you’ve been exposed to all of the same information I have, and even if you know what an outline is and how to use one, it might be good to remind ourselves of how valuable they are.

If you assume I’ve gotten today’s theme for the piece from my idea repository, you’d be right most of the time. Once I have that idea ready, though, the piece doesn’t exactly write itself. Not quite, anyway.

Instead, I need an outline. Usually, I have a title in mind, and I really enjoy flowing from the title into an intro. But as I’m starting to craft the intro, I need to pause to work on the outline for the whole piece, so I can get an idea of the 30,000 foot view.

Ever try drawing a face when you’re up close to the face? You can really focus on one detail at a time, but pretty soon, you have some kind of inhuman looking mess on your paper. Why? Because you didn’t start with an outline, or at least a rough sketch of where everything should go first.

Writing is exactly like this.

Think of an outline as a way to divide what you’re working on into three distinct parts: the intro, the body, and the conclusion.

Is that oversimplifying? Does that limit the world of prose available to you? Yes it does! And, that’s a very good thing, unless you’re deliberately trying to make this about how weird you can make the format.

Still, virtually every piece functions well with some kind of opening salvo and a conclusion that ties everything together, perhaps summarizing (but not too much). The body is just the stuff in between.

The journey to becoming a better writer is both deeply personal and widely relatable. It's a blend of discipline, inspiration, and methodical organization—traits I've honed over years of daily writing and other long-term commitments like Brazilian Jiu Jitsu.

On one hand, the outline and idea repository allow me to plan and prepare. My OCD brain really likes that! On the other hand, I get to be spontaneous within that framework, and my ADD brain loves that!

Whether you're someone who has the luxury to write every day, or someone who can only find pockets of time here and there, the most important thing is to get started and keep going. If you can’t write every day, write every week! Use the repository to keep track of ideas as they pop up, and use outlines to plan.

I’m here to encourage you to take that next step. Carve out a routine, create an outline and write! If an idea seems silly or fleeting, jot it down anyway and look at it later.

The path to becoming a better writer is a lifelong journey, one that thrives on discipline, flexibility, and, most of all, a willingness to keep putting pen to paper—or fingers to keyboard.

Are you a technical writer in search of a community of like-minded creators to share and grow together? Join our community, it’s free!

Join the Tech Writers Stack

Do you have any super secret ninja techniques about writing that you want to share? Leave us a comment and come write with us!

Leave a comment

This post describes a loose workflow I have recently developed for quickly drafting new articles while on the go.

A while back, I published a comprehensive guide on writing technical articles. I outlined a six-step process for transforming a messy idea into a polished article in that guide. The steps can be followed loosely, guiding you from disorganized thoughts to a well-structured outline and, ultimately, a refined piece.

Mostly Harmless Ideas

How to Write Technical Articles

Read more

3 years ago · 22 likes · 9 comments · Alejandro Piad Morffis

If you don't want to read the full article, here's the gist of it.

You start by brain-dumping all your ideas onto paper (or electrons). You distill the most important concepts and extract the main talking points. Next, you rewrite these ideas, organizing them into a logical outline. Finally, you polish and refine the content. This way, your thoughts move from a jumble in your mind to a coherent structure on paper.

I intentionally did not specify a particular toolset in that article because it works even with pen and paper. However, at the end of that guide, I mentioned that you can use generative AI tools to enhance the process without losing your voice.

In this article, I will present a specific implementation of this process that diverges slightly from the original and relies heavily on generative AI, but in a good way. This approach allows you to increase productivity without losing your voice and style and makes writing much more enjoyable, at least for me.

I will also detail the tools and the exact workflow and prompts I follow. Hopefully, this will help you implement this process rather than just reading another ultimate writing productivity guide.

Let's go.

The workflow

At a high level, the process can be summarized as follows.

First, I record myself speaking about the main ideas behind the article, which can be done in multiple sessions. This talk is unscripted and doesn't require any initial structuring. It can be a spontaneous rant or a slightly more organized discussion. The main goal is to brain-dump my thoughts without overthinking them too much.

After recording, I use Whisper to transcribe the audio, which removes filler words and other extraneous sounds —like hums and ahhs. So, although the transcription is already cleaner than the original audio, it still includes repetitions and lots of unfinished, messy ideas —unless you're really good at improv talking.

Next, I skim the transcription and divide it into coherent sections based on its internal organization. If the transcription is from multiple recordings, each one often corresponds to a different main idea since I stop and restart recording whenever I change topics. However, if it is just one long recording, I may need to manually separate it into meaningful sections of around 200-300 words.

Now comes the magical part. I will use a large language model like GPT 3.5 or 4 to rewrite and improve the text. I designed a simple prompt —which I’ll show right away— that asks GPT to retain the content while making the text more understandable and improving the style. This rewrite becomes the first draft.

Next, I paste the draft into a text editor and make two editing passes.

The first pass involves rewriting anything that doesn't sound like my voice, as the AI will take poetic liberties that alter the original meaning. I also fix any errors or inaccuracies the AI introduced in the rewriting process. Finally, I make adjustments to remove fancy words chosen by the AI —like the infamous eliminate, utilize, or delve— that don't really match my style and add anything that I think is missing, such as headings and connector sentences. This is the first major rewrite.

In the second and final pass, I polish the text more finely, carefully rounding the main ideas and doing laser-focused edits to get to the most refined version of the text I can. But again, without excessively overthinking it.

After these two passes, I consider the text ready to publish.

Are you a technical writer looking for a community of like-minded creators to share experiences and grow together? Join the Tech Writers Stack today! It’s free.

Join the Tech Writers Stack

Implementation details

Now, let's discuss the nitty-gritty implementation details.

For the transcription part, I already mentioned I use Whisper. There are various apps out there you can use. Still, I prefer this self-made Telegram bot that has the convenient feature of concatenating multiple audio messages into a single text note. Once the process is complete, you will receive the final transcript. You’re welcome to try the bot for free.1

Moving on to the editing part, you can simply use ChatGPT with the following prompt (in my experience, both 3.5 and 4 give similar results for this case):

You are a proofreader. Your task is to rewrite the input text by keeping the same meaning but improving the grammar, style, and punctuation. Make sure all sentences are in active voice, crisp, and to the point. Start each paragraph with the main idea and continue with the supporting claims. Do not add any content that is not in the original text.

{{ Input text }}

However, to simplify this process, I prefer using Bearly.ai, which offers a streamlined UI that cuts all the chatty nonsense. I made a template with the previous prompt, allowing me to paste the transcribed, messy text and get a revised version back with a single click.2

Occasionally, I will run the generation process twice. Still, I often prefer to just manually adjust the result instead of regenerating until I hit the jackpot with the exact wording I was looking for.

For manual editing, I am not particularly fond of the Substack editor. It lacks many features and can be cumbersome, especially if you're a fast typer used to goodies like multiple cursors and lots of hotkeys.

Instead, I prefer using a full-featured desktop editor like Obsidian. I copy and paste the initial draft into it for the bulk of manual editing. Obsidian offers only basic spell correction on the linguistic side, which means it's just me and my writing. No more AI.

Afterward, I transfer the edited text to the Substack app for the final pass and adjustments, including adding subscribe buttons, illustrations, footnotes, links, and the typical calls to action.

In the Substack editor, I also have the Grammarly plugin turned on, which provides helpful suggestions for simplifying and polishing the text. Generally, I accept about 50% of Grammarly's recommendations, particularly eliminating passive voice and reordering sentences. However, I ignore the remaining 50% of stylistic preferences I don't necessarily embrace.

Final remarks

Once the editing process is complete, many say it is advisable to let the draft rest for a few days before revisiting it and seeking feedback from others. But, in any case, publish your work while it’s warm. Don't let it wither in your draft list, or it will fade into oblivion, never to be finished. It becomes a zombie draft, not alive but unwilling to die completely. Trust me, I've been there.

The beauty of this workflow is that it relies heavily on generative AI, but only for the most boring, uncreative part: taking your unpolished but genius ideas, transcribing them, and giving them some initial structure. The kind of work you would trust an intern to do. And it does so marvelously.

But in the end, it's you at the steering wheel. You provide all the ideas and initial content and decide which exact word survives the final cut. This is the right way to use AI as an empowering tool, not a sad substitute for lazy writers. This workflow won't remove all work, but it does remove the bulk of the boredom and leaves you all the entertainment and excitement to enjoy. It's your writing.

However, this process is not suitable for everyone or every kind of writing. It is especially useful for technical writing, in the broader sense of writing meant to inform on technical topics. For the more creative writing, you almost certainly aim for more precise wording. Likewise, for the more emotional kind of essays, I tend to write them from scratch.

That's it. Feel free to copy, modify, and share this workflow as you see fit. I hope this method makes your writing more productive, but also more enjoyable, which matters even more. For me, it certainly has.

At the Tech Writers Stack, we’re always looking for writers like you to share your experiences. If you want to write for us or cross-post something you’ve already written, leave us a comment.

Leave a comment

Appendix

As an addendum for completists, here is an example of this very article going through the different phases. This section is just meant to show you how feasible this workflow really is. Skip it if you're already sold.

Here is the audio recording of the first section, which ended up being the introduction. Don’t listen to it fully; just notice how unscripted and spontaneous I talk. Also, don’t worry about your accent; mine is pretty thick, as you can hear, and Whisper got it perfectly.

From that audio, my Whisper-powered bot gave me the following transcription (I’ll show only the first few sentences). You can see how Whisper does a pretty good job removing filler words and weird sounds, but still, the text is really really unpolished.

This post is to explain a workflow that I've kind of been converging lately to quickly draft new articles while I'm on the go.

A few weeks ago, a few articles back I published a longish guide, technical guide, on how to write technical articles.

In that guide I highlighted a six-step process that are kind of very structured but you can take them loosely and that those processes are designed to go from a very messy idea inside your brain into a clear article.

So the way I suggest you to review that article if you want but here's the very quick summary.

The way this process works is you have some messy idea in your brain and before simply sitting down and typing that you kind of have to organize your thoughts.

So the process goes from first brain dumping everything that you have and then trying from there to distill the most important ideas and extract the main talking points and then rewrite everything that you all the ideas that you had to organize it into an outline that makes sense and finally do the editing and polishing.

…

From this unpolished text, using my proofreader prompt, I got the following first draft:

This post aims to describe the workflow I have recently developed for quickly drafting new articles while on the go.

Previously, I published a comprehensive technical guide on writing technical articles. Within that guide, I outlined a six-step process that provides a structured path for transforming a messy idea into a clear article. While the steps can be followed loosely, they effectively guide you from disorganized thoughts to a well-structured outline and, ultimately, a refined piece.

To begin, you start by brain dumping all your ideas onto paper. From there, you distill the most important concepts and extract the main talking points. Next, you rewrite these ideas, organizing them into a logical outline. Finally, you polish and refine the content. In this way, your thoughts move from a jumble in your mind to a coherent structure on paper.

You can see it’s pretty close to good enough. I then manually edited that to bring to the actual introduction of this article. All of this took me no more than three hours, 80% of which I did on my phone while waiting in a line at the supermarket. I did the final 20%, including the Substack-specific bells and whistles, sitting back home at my computer.

Technical writing is a skill anyone can develop. Writing online for technical audiences brings many benefits with little to no downside other than the time you have to spend. In this short article, we review the main reasons why technical writing is good for you, whatever your profession and interests, and give you some tips on getting started. But before getting there, let’s talk briefly about what we mean by “technical writing.”

What is Technical Writing?

Technical writing is the type of writing that is meant to transmit information or knowledge about a technical topic. We can contrast it with creative writing —e.g., fictional storytelling—, political writing, humor, and news. Frontiers are fuzzy, of course, and technical writing can incorporate elements from, e.g., creative writing to make it more compelling to readers —if you need inspiration, read .

The difference between technical writing and other forms of writing is in its purpose: technical writing is primarily about producing some novel understanding of a concrete topic in the reader. Technical reading can and should be entertaining, inspiring, etc., but that is always a complementary objective.

Technical writing is not necessarily restricted to technological or scientific topics. In the broadest sense, “technical” just means something related to a specific discipline or technique. You could write about coding, math, or science, but also about cooking, gardening, drawing, playing a musical instrument, or even, like this article, about writing itself. You can write about your job, your hobbies, or anything you’re currently learning.

Why you should do it

The previous section underscores the simple fact that anyone can do technical writing. There’s always something that you know and someone else would benefit from knowing. And that’s probably the most common motive for someone to engage in technical writing: giving back to the community. But even if you’re not interested in sharing knowledge, you will still get concrete benefits from having your own technical blog.

A technical blog is great for people who like learning and thinking clearly. There are many reasons why it's helpful.

It improves your thinking

When you write down your thoughts, you can see them in front of you, which helps you think more clearly.

For instance, if you're trying to make an important decision, writing down the pros and cons of each option can help you analyze the situation more effectively and make a better decision. That process can then become a guide for future people facing similar challenges.

Additionally, when you keep a journal of your thoughts, you can look back at old entries and see how your ideas have evolved over time. You will find connections among topics you didn’t know were related. For example, you might notice that you used to be more anxious or negative, but now you're more positive and optimistic. This can give you insight into your own personal growth and help you learn new things about yourself.

It helps you grow intellectually

When you share your ideas online, you open yourself to new perspectives and opinions that can help you grow intellectually.

For example, if you share your thoughts on a particular topic in a discussion forum, someone else may offer a counterargument that you hadn't considered before. This can help you refine your ideas and broaden your understanding of the topic.

Similarly, if you share a blog post or article, others may offer feedback or suggestions that can help you improve your writing and communication skills. If you are really interested in having the best ideas, there’s nothing like feedback from your peers.

It works as an external memory

Writing down your thoughts will be invaluable next time you’re arguing about that same thing again. Don’t waste time rethinking all those careful arguments. Share a link to your blog.

Let's say you wrote a blog post about the benefits of a particular type of exercise. If someone asks you about those benefits, you can easily share the link to the blog post instead of typing a lengthy response. Or, perhaps you wrote a tutorial on how to make a certain recipe. If someone asks you for the recipe again, you can quickly share the link to the tutorial for them to reference.

It works as a curriculum

A blog is also a great way to showcase your knowledge and interests to potential clients or employers.

For instance, if you are passionate about cooking, you can create a blog that features your favorite recipes, cooking tips, and food-related news. Or if you are interested in fashion, you can use your blog to show your personal style, share fashion trends and news, and connect with others who share your interests. And if you’re into coding, you can show off your technical knowledge.

This can lead to job opportunities in whatever industry you’re writing about. Your writing works as a curriculum that is more than just a list of skills on a LinkedIn page. It’s an actual showcase of those skills, demonstrating that you possess the technical abilities and the communication skills to make yourself understood.

It gets you to meet people

When you write in an online community like Substack or Hashnode, you can collaborate with people who share similar interests. For instance, if you are a writer who specializes in science fiction, you can connect with other science fiction writers to discuss your craft, share ideas, and give each other feedback. By working together, you can help each other grow as writers and develop your skills.

Similarly, if you are a software developer, you can join a community of developers on Hashnode to discuss your coding projects, ask questions, and get feedback from other developers. This can help you learn new programming techniques, discover new tools and resources, and improve your coding skills.

Ultimately, writing in an online community can be a great way to connect with like-minded people and collaborate on projects that interest you. Whether you are a writer, a developer, or someone with another passion, there will surely be an online community where you can find people to work with and grow alongside.

But what if…

I hear you. Even if you agree with the above, many things keep you from starting. Let’s debunk some of the most common fears.

…I have nothing to share

That’s just not true. Let’s do a quick experiment. Think of something you’ve learned in the last year: a new professional skill, an interesting topic you’ve been obsessing about, whatever. Don’t struggle to find something you’re a world-renowned expert at. Just something you didn’t know a year ago, and now you know a bit about.

Got it? Well, there you go. Write for the person you were 1 year ago. That’s your audience.

There is someone out there, right now, who is in the exact spot you were 1 year ago, and you can help them get to where you are today. Think about how awesome it would have been to find someone like who you are today, for who you were 1 year ago. Be that person to someone else.

What? Someone already wrote about that topic? It doesn’t matter. Your perspective on it is unique. You went through a specific process to learn that thing, and no one has written about it from that exact perspective. Share your specific struggles when learning this stuff and what you did to overcome them.

Believe me, there is someone out there for whom your story is the exact thing they need to read.

…no one reads what I write

So what? Most of the benefits we’ve mentioned don’t require a large audience. You can write for yourself and still get a lot of value out of it.

However, I get it. It’s a real concern. And let’s be real. At first, no one will care —maybe your close family and friends. But I can assure you that people will notice you in time, and a small core of real fans —or friends— will grow around your writing. And if you use one of the many platforms, like Substack or Hashnode, with strong network effects, you’ll grow much faster than you believe.

Even better, join the Tech Writers Stack community, and you’ll get at least a couple dozen guaranteed readers. Not only that, many of us are also technical writers, so that we will look at your stuff with the eye of a friendly critic. Tag me whenever you post something, and I promise to read it and give you feedback.

…it takes too much effort

Yeah, writing does take some effort. You have to develop ideas, research, write, edit, polish. But there’s no rush. You don’t have to match any goals here other than your own. You don’t need to commit to a weekly article, or monthly, or anything. You can set your own pace. As you become more accustomed to putting your thoughts on (electronic) ink, it will get much easier.

Plus, there are some concrete things you can do to make writing more enjoyable and productive at the same time. Check out our Tech Writing Bits sections for some insightful articles on techniques and mindsets you can use. Also, read our Tech Writer Highlight series to understand how other technical bloggers approach their craft. You’ll notice there’s no formula, and everyone has their own process.

Conclusions

There’s really not much else I can say. You can start your own technical blog today. Or you can come and write with any of us if you’re undecided. Technical writing is something you can master, and it will pay you back in more ways than you can imagine.

Leave us a comment if you want to find collaborators or mentors. All of our community is here for you.

Leave a comment

So don't wait any longer. Start your blog today.

“Just start writing. This is most certainly not unique or earth-shattering advice, but it’s important.” -Abbey

Writing is an incredibly complex task, and writing about technical concepts is astronomically harder and more complicated. On that note, we did what every hard-core learner would do when faced with a challenge; we sought the input of an expert.

Abbey has been FreeCode Camp’s chief Editor for 6 + years and, as a result, has reviewed thousands of articles with varying levels of technical complexity, which made her the perfect guest to answer our question of “How do you write a great technical article/essay” and on that note, we had Edem go talk to her and see if we could get some tips on how to level up our (and your) writing. The conversation is shared below.

Subscribe now

Edem: Hey Abbey, It’s great to have you here! Could you tell us about yourself, your professional qualifications, and such?

Abbey: Thanks for including me, Gold! I've been working full-time with freeCodeCamp as our head editor and social media manager (and so on - we're a small team!) for about five and a half years now. I was a volunteer editor for about 8 months before that. 

Before joining the freeCodeCamp team, I was writing a book and a blog, as I was in between jobs - so I got a lot of writing and editing experience doing that.

In my "previous life," I studied Mediterranean archaeology and got to travel all over Europe and the Middle East working on excavations. I also studied Latin, ancient Greek, and several other languages for my university degrees. So I guess the study of words and language has always been part of my academic and adult life.

Edem: Incredible, What role does technical writing play in your daily life?

Abbey: You could say that technical writing plays a very large role in my daily life - but it's mostly other people's writing since I'm an editor. I've read and edited thousands of tutorials at this point on almost any technical topic you can imagine. So there's never a dull moment!

I used to do more writing myself, but I've been quite busy with my editorial and other tasks over the past couple of years, so I write less than I'd like. I think I enjoy editing as much as writing, though, so it works out. There's a certain satisfaction you get from helping other people polish and prepare their work to be released into the world for other people to learn from. You feel part of something bigger.

Edem: Let’s start with something a bit philosophical. How does Technical Writing shape our understanding of technology?

Abbey: How does technical writing shape our understanding of technology - what a great question. I think the way that an author explains a technical concept actually has a significant impact on how readers are able to understand that concept. If a writer uses clear, direct, simple language, chances are the reader will understand what's being taught a lot more easily. This may seem obvious, but it's not always easy to do.

They say that if you can teach something, it means you understand it really well. And I'd add that in order to teach something effectively; you have to understand it inside and out. So if you can explain something to me like I'm 5 (or maybe like 10 for our purposes - let's be realistic here), that's a great sign - and I'm probably going to grasp the nuts and bolts much more easily. Then we can build upon that simple foundation and develop a more complex understanding.

So anyway, a person's writing style is very important. I always encourage authors to write as if they're explaining something to a friend. This keeps the tone straightforward, friendly, and helpful and typically makes the info easier to grasp. This is in contrast to, say, writing an academic paper (for which the style would be quite different, but not always as easy to take in. I used to be in academia, so I think I can say that!).

Edem: That does make sense. How can a good article make a piece of technology more accessible?

Abbey: I'm going to start off by answering this a bit indirectly, but I think you'll see my point in a minute: sometimes, authors write to me asking if they can or should write an article on some (seemingly) basic topic - like functions in JavaScript, or loops in Python - about which many other people have written. They're worried that they won't have anything new to add to the conversation.

But I almost always tell those people to write the article anyway. Because the way that they explain that particular topic might just click with someone, whereas other tutorials didn't.

Now, of course, this isn't as likely to happen if the article isn't high-quality, well-written, clearly explained, and correct. But as long as it's a solid take on a topic, it's going to help someone.

So, to get back to your question - I think a good article is critical for helping learners understand basic concepts. You've probably heard the phrase "tutorial hell" - it's a term I came across many years ago, and freeCodeCamp has actually published articles about it! But if you take a well-written and clearly-explained tutorial and put into practice what you learn from it, you've gone from potential tutorial hell to another, better place. (I don’t know, should we call it “builder’s paradise”...?? :))

The benefit of a good tutorial is that it can explain things in a way documentation might not be able to. There might be that personal touch, that bit of humor from the author, or just a different and perhaps simpler interpretation of how something works. And I think those things are key.

Edem: Let’s get down to the crux of what makes a technical article good. In your years of experience as an editor at FreeCode Camp, you’ve reviewed tons of articles. Is there a sweet spot number of words that makes the most popular articles?

Abbey: I love this question - is there a sweet spot number of words that makes the best or most popular articles? I love it because my answer is no.

It really depends on what you're trying to accomplish with the tutorial. If it's just a quick guide to a particular feature of a language or framework, you might only need a few hundred words. If you're trying to go more in-depth, walk through a project-based tutorial, or teach a more general topic, you might need a few thousand or more. We also publish handbooks and books, which can range from 10,000 words all the way up to 50,000 or more.

My point is this: write just as many words as you need to do your topic justice. No more, no fewer. The tutorial should be as long as it needs to be, in your opinion, to fully cover your subject matter.

Edem: What are the most common mistakes people make when writing articles?

Abbey: Well, there are various types of mistakes writers can make. There is the grammatical/spelling/typo kind, which we all make once in a while. This is where doing some good proofreading can come in really handy. When you're submitting an article to be reviewed by a publication's editor, it's a good practice to make sure you've read through your article a few times to catch as many of those as possible.

Then there are the content-based types of mistakes. Perhaps the writer doesn't understand a topic as well as they should, or they found incorrect information somewhere on the web. Luckily, these are rare, at least for us. The writers I'm fortunate enough to work with are quite diligent in their research and careful in their writing. But every now and then, we catch small things.

So as a writer, I'd just say make sure you do your research, test your code, and don’t share anything with the world unless you’ve proofread, fact-checked, and are overall satisfied with the quality.

Edem: How important is the Title in an article, and how do you get the perfect title considering SEO, relatability, and simplicity?

Abbey: I think the title is quite important - as Quincy likes to say, it’s the only part of your article that basically everyone will definitely read. So it’s important to craft an engaging, informative, and search-friendly title.

Sometimes, I like to think about what someone would be searching for that would land them on this article. That can help you craft a good title.

We tend to stay away from listicles and sensationalist or click-bait titles, as we’re a purely educational publication.

Edem: What separates a good article from a great article?

Abbey: I think many things can separate a good article from a great article. Sometimes a good article is good enough. Does it provide accurate information? Does it help solve a reader’s problem? Does it provide helpful and clear examples? These are all features of good articles.

I think a great article just goes a bit beyond what’s strictly necessary. Perhaps the author writes in a particularly engaging style. Perhaps they add (appropriate and helpful) humor here and there. Perhaps they create their own detailed diagrams and images. These are all features that go above and beyond, in my opinion.

Another way authors can make their drafts stand out - at least for me - is by demonstrating that they’ve thoroughly proofread their articles. This may sound simple, but it’s actually quite difficult to submit a really “clean” article that requires very few edits. But honestly, the fewer edits I have to make, the better. And this is in part because it means that the author took great care to prepare the article for publication (and to potentially be viewed by millions of readers around the world).

Ultimately, our mission is to help people learn how to code for free. So any article that does that effectively is a good article in my book. This doesn’t mean it’s easy to write a truly good article - it just means it’s not magic. It just requires hard work.

Edem: What does a bad technical article look like?

Abbey: I think the most detrimental things to a technical article are a lack of clarity in writing, a lack of explanation of the code or examples, sloppy or hard-to-understand writing, unnecessary complexity, and, of course, factual inaccuracies.

Remember, when you’re writing a technical article, you’re trying to teach someone something. This person may not know anything about your topic. They may know a little. Or they may be a relative expert. But you should try to explain concepts in a way even a beginner can understand (unless you’re specifically writing on an advanced topic or intend your tutorial to be for more advanced developers - which you should state in the article).

If you lose sight of this educational aspect - the goal of the tutorial - then the article becomes much less helpful.

Edem: How do you make articles more engaging and readable?

Abbey: Well, freeCodeCamp has a style guide that’s dedicated to helping authors write really clear, readable, engaging tutorials. So the tips in there should be really helpful.

Some general things to keep in mind: don’t write super long and complex sentences (or paragraphs). They’re hard to read. Don’t overuse formatting. Keep things simple and straightforward. Try to let your personality shine through in your writing a little if you can (and want to do that). It’s nice to “hear someone’s voice” when you’re reading their tutorial. Things like that.

Edem: Technical Articles are mostly about really complex concepts. What is the best approach to introducing really complex concepts to readers without making it boring and losing any of the core required complexity?

Abbey: I do believe that if you truly understand something, you can probably explain it in a way beginners would understand. I think one of the hardest things for more experienced devs to remember is that a topic they consider easy may not be easy for everyone.

Try to think back to when you were first learning about arrays or Big O notation or loops or [insert any topic here]. How’d you learn about it? What made it click for you? What do you think people should know about this topic to really help them understand the nuts and bolts and how it really works?

It’s ok if a topic is complex. The fun part, and the challenge, is to explain it in a way so that someone who doesn’t know anything about it can get the basic gist of it. Be clear, use short sentences and smaller words, use lots of examples (and explain the code line by line when needed), and again - make sure you understand it really well, first.

And again, it’s always helpful to let readers know whether what you’re writing is a beginner-friendly tutorial, or whether it’s made for someone with a bit more background knowledge. Sometimes a simple prerequisites section along with a basic intro to what you’ll be covering is really helpful.

Edem: What are your thoughts on the future of Technical Writing?

Abbey: I believe it’s important to have many different perspectives on the same topic. As I discussed above, every author will explain x topic a bit differently, and that might be the explanation that clicks for someone. So I think that’s a big benefit that technical writers bring to the educational space: their different experiences, knowledge bases, and perspectives.

It’s hard to say what will happen over the coming years - many people are experimenting with AI tools, and that’s great. But another benefit of technical writing is that it’s a great way to learn a topic really well. So it’s helpful to the author as well as to people who might read their work. I don’t think that’s something we should forget. (Ya know, the actual learning part :).)

Edem: What are some of the best resources to learn how to write Great technical articles?

Abbey: Read a lot of great technical articles! :) This will give you a sense of what works, how other writers explain things effectively (and when it’s not so effective), and how you may want to structure your own tutorials.

I know there are actual resources out there - courses, books, etc - but experience is also key. Just write a lot. Work with an editor. Have a friend read your work and give you comments. Have the desire to get better. Ask people to coach you or give you tips. I’m always happy to review changes with authors or give general feedback, for example.

Edem: Let’s talk about your work at freeCodeCamp a bit. I have no doubt you get a lot of submissions daily, some really lengthy (like mine) and with varying levels of complexity. How are you able to go through them efficiently?

Abbey: It used to take me hours to edit one article. Now I’m pretty quick. I know what to look for, and after almost 6 years of doing this full-time, it comes much more easily to me now.

Some articles take longer than others, depending on the amount of editing I feel I need to do. But I just work through the submissions as best as I’m able. It does help that I enjoy the work, so typically it breezes by.

I also have an editorial team now, so I have help! It’s wonderful to be able to work with editors who are also authors, as they have a great sense of what needs to be changed when something doesn’t make sense, and so on. So that’s super helpful.

Edem: What advice would you give to someone about to begin his or her technical writing journey and wanting to build a niche and career out of it?

Abbey: Just start writing. This is most certainly not unique or earth-shattering advice, but it’s important. The more writing experience you have, and the more you try to improve, the more likely you’ll be able to publish your articles beyond your personal blog.

But start a personal blog - that’s a great place to practice. Write about what you’re learning or about what you want to know about. Write to help others. Publish your articles on tech publications as you’re able. Build up your portfolio. And seek help in improving your writing if you think it needs some work.

Edem: What advice would you give to someone transitioning from full-time engineering or academia who wants to become a writer?

Abbey: I think many careers are great precursors to becoming a technical writer. If you were an engineer who’s looking to get into writing, use your knowledge to write great technical articles and show what you know. If you were in academia, chances are you’ve done a lot of writing already. Just adapt your style to be a bit more approachable and less formal.

Just use the skills you already have and apply them to writing. Many of the skills we build up in our careers are transferable - we just sometimes have to be creative about it.

Edem: Thank you very much for your time Abbey. It was incredible! Any closing words?

Abbey: Thanks for asking me to share my thoughts! I really enjoy working with all the wonderful, intelligent, kind authors that I get to work with as part of my job at freeCodeCamp. It’s a pleasure to help them share their knowledge freely with the world, and I’m grateful to them for it.

So go forth and write! Share what you know. It helps make the world a better place.

Leave us a comment if you have a question for Abbey and we’ll pass it through.

Leave a comment

And remember you can share this newsletter and get cool rewards.

Share

Subscribe now

There's a book on my shelves called Principles of Optics. But no one ever uses the book's name. Everyone who knows about this book refers to it as Born & Wolf after the two authors. This is the optics textbook, as classic as it comes. The Shakespeare of the optics world, if you like.

Except that, it's not Shakespeare. This is a science textbook from a different era. Max Born, one of the authors, was a key figure in early twentieth-century physics, especially in the field of quantum mechanics, for which he won the Nobel Prize in 1954. He's also Olivia Newton-John's grandfather, but I digress.

The in-joke in the optics world is that everyone has a copy of this book on their shelves, but no one has read it. My copy is in pristine condition—and over 20 years old. I remember the day I bought it. I was in the shared office I used as a PhD student, and a senior colleague walked in as I unpacked the book: "Ah, you've got that expensive paperweight, too!" The book contains fact after fact and derivation after derivation, an interminable string of impenetrable words.

Technical writing has moved on from this thorough-but-dreary style of writing. But too much of it can still be a bit dull. Does it matter? Isn't the purpose of technical writing to convey accurate facts that the reader can absorb?

Yes. And No. The key purpose is for the reader to understand the topic. So shouldn't a technical article use all the techniques available to help its readers understand the topic as best as they can?

Why not borrow techniques used by fiction writers and storytellers? After all, a novelist's writing is perfected to convey key messages effectively while keeping the reader interested and engaged.

Narrative (from the Latin narrare meaning 'to tell' or 'to relate') — To tell a story or relate a series of connected events

Narrative Technical Writing — Writing about technical concepts using techniques borrowed from storytelling

Spoiler Alert (or Overview of the Article)

We can borrow techniques from storytelling, but narrative technical writing is not fiction. So I can "spoil" the story for you by telling you what's coming. But don't worry, there are still twists and turns in the plot.

• Why humans react better to stories than facts: I'll discuss the premise of this story and how we have always thrived on narratives.

• My three categories of technical narration: This article is a personal perspective. So I'll try to verbalise the different ways I add narration when writing technical articles. The following sections discuss each category in more detail.

  • Narration through analogies: Analogies are a powerful tool to help understand abstract concepts. I'll explore them in this section of the article.

  • Narration through story-framing: We can frame our technical article within the context of a story to make it more memorable and more engaging for the reader. I'll look at some examples.

  • Narration through technical detail: Are there any techniques used by storytellers we can use directly within the technical content and not just in accompanying analogies and framing stories? Well, I'd hardly dedicate a section to this if I thought the answer was 'no', right?

• Using a narrative writing style and language: The language and writing style we use in technical writing is often very different to that found in novels and other stories. But does it have to be that different?

Let's start from page one.

We're All Story Addicts: Here's Why

In this article, I'm writing about my personal perspective on introducing narrative elements into my technical writing. And I'm proposing to borrow techniques from fiction. This doesn't mean I'm making everything up!

Storytelling has been an integral part of all human societies throughout history—and not just as a source of entertainment. Stories have been used to shape societies and how they think.

Homer's poems and the Sanskrit epics reflected and affected the cultural and moral norms in their respective societies and beyond. Biblical stories influenced people over centuries, and still do. The legends of King Arthur and Shakespeare's plays, and more recently, novels such as 1984 and Brave New World, have had important roles in societies questioning their views and norms.

And for many of us, Anne Frank's The Diary of a Young Girl and Steven Spielberg's Schindler's List have brought to life the harrowing nature of the Second World War better than most factual history books ever could.

These are not just stories for entertainment. They're communicating ideas to the reader. They teach us facts or tell us the authors' opinions on certain matters. There must be a reason why stories are a part of every society throughout history.

But there's also a growing body of scientific evidence to confirm that storytelling has a special role in our brains. As tempting as it may be (it isn't!) to hark back to my days as an academic and delve into a lengthy literature review, I won't. (There are links at the end of the article for those interested.)

Stories activate parts of the brain that are not generally associated with language. Therefore, your brain reacts differently when reading stories compared to when you're reading facts. Good storytelling likely brought an evolutionary advantage in terms of enhancing cooperation and social cohesion, learning, understanding, and transmission of knowledge.

Even during REM sleep, which is critical for learning and understanding, our brain dreams by creating stories. We can't escape stories, not even when we're sleeping.

Stories also bring in emotions that can be used to help the reader understand the topic from a different perspective. They evoke mental images in a way that raw facts don't. Stories are also more easily memorable than facts.

And if the purpose of technical writing is to guide the reader to understand and remember abstract concepts, why not use techniques that have worked for centuries and millennia, backed by growing scientific evidence?

The Three Flavours of Narration in Technical Writing

This article is a snapshot of my thinking about this subject. It depicts the current stop on my journey as I experiment with my technical writing. My starting point was in scientific research. There are no stories in journal papers. And I'm not suggesting narrative technical writing should replace the more rigorous scientific writing needed in scientific journals.

But I was always eagerly waiting for the opportunity to break loose from this restrictive form of writing. So, when I started writing Python tutorials and articles, I felt I had already paid my dues and had a licence to experiment.

There are three distinct categories of narration I've been using in my technical writing:

1. Narration through analogies

2. Narration through story-framing

3. Narration through technical detail

As this article is a reflection of how my thinking and writing changed, I'll use examples from my own writing. But there are other technical authors who use narrative techniques. As I'll be writing again about storytelling in technical writing, I'll highlight other authors in future musings about this topic.

1. Narration through Analogies

Using Analogies to Clarify Technical Concepts

The first of my technical narration categories is probably the easiest to describe. Analogies are a powerful tool to explain and understand abstract concepts. They help us visualise these ideas through everyday experiences that we understand well.

As a student at school and university, I recall coming up with analogies when learning science and maths concepts. I've used this tool over many years to help me process the concepts I'm learning.

An analogy is not necessarily a "story". But it can be one. It's always a description of a sequence of events. The analogy often describes everyday items and events, but this doesn't mean it's easy to craft and write. Some of the most powerful descriptions in literature describe everyday occurrences in a way that highlights certain aspects of those items or events that the author wants you, the reader, to visualise more prominently. The same is true when creating and writing a technical analogy.

There are two key challenges when explaining technical concepts using analogies:

• Choosing the right analogy

• Connecting the technical topics to the components of the analogy

But first, let me give you an example of an analogy I like to use. I'll get to these two points later.

Monty and The Room Analogy

This is an analogy to describe the structure of a computer program in Python and what goes on when you run a program. The analogy has evolved over the years I've been teaching programming. I'll give you an executive summary below, but you can read it in full here: The White Room: Understanding Programming.

It starts with an empty room. The room represents the infrastructure in which the computer program runs. I said it's empty, but that's not quite true. There are some shelves on one of the four walls. And there's a small red booklet on the bottom shelf. This booklet has references to built-in functions, constants, and keywords.

There's also Monty, a friendly avatar who follows your written instructions and gets things done. In many ways, Monty is the personification of the computer program.

When you import a module, Monty leaves the room and goes to the big library in the centre of Python City, fetches a book with the module's name, and brings it back to the room, placing it on one of the shelves.

When you assign a value to a variable name, Monty fetches a box, puts the object inside the box, and labels the box using the variable's name. He places the box on the shelves.

And when you define a function, Monty builds a new room adjacent to the main one, with a door linking the main room to the function room. The function's name is written on a label on the door leading to the function room.

A learner can use this analogy to create a visual image of Monty and the rest of the analogy's components. When they read or write Python code, they can map the abstract code to the clear mental image they have of the rooms, the boxes, the books, and so on. This exercise translates the technical processes that happen in a computer program to concrete everyday actions that we can all easily visualise. Here are some examples:

Abstract concept: Use an existing variable name in the code.
Action within analogy: Monty looks for a box labelled with the variable name, brings the box down from the shelf, and fetches the contents of the box.

Abstract concept: Call a function with one argument. Function returns one value.
Action within analogy: Monty looks for a label with the function name in the main room. He finds it on a door leading to another room. He picks the object referenced in the function call's parentheses (the argument) and walks through the door to the function room, taking the argument with him. When Monty performs all the actions in the function room, he returns to the main room, taking the result from the function room with him.

This mapping between abstract and concrete helps a learner understand what's going on. But it also helps them recall the process later. There's no need to memorise the abstract steps since the story the analogy tells is memorable.

Let me return to the two challenges we face when using narration through analogies.

Choosing the right analogy

Finding a good analogy is not easy. It needs to describe an item or event that's sufficiently common. Most of your audience should have experienced this situation and understands it well. It can't be too specific or niche. For example, using a cricket match as an analogy will work for some audiences but will not make sense to many more. This defeats the purpose of the analogy since you're replacing an obscure process that's not clear to your audience with another scenario they don't know much about.

The Monty analogy works well since it talks about boxes on shelves and rooms with doors. They're concepts everyone understands very well.

An analogy can't be too contrived, either. You'll probably lose your audience if you force them into mental gymnastics to link the abstract concepts with the items and events in the analogy. I'll talk more about this in the next section.

Another fine line with analogies is knowing when to stop diving further. No analogy is perfect and will break down if you go into too much detail. This is fine since your audience understands you shouldn't take the analogy literally. But when you reach a certain level of detail in your topic, you may need to stop using the analogy. Don't push too far!

Connecting the analogy's components to the technical topic

The second challenge with analogies is specific to how you present them. When you first introduce the analogy, whether in writing or verbally, you guide your audience into creating a mental picture of the scenario. This is a similar skill to describing a scene in a novel. The author tries to create a clear picture of the scene in the reader's mind, focusing on the things that matter most.

You need to use your descriptive writing skills when writing an analogy to emphasise the key items and events in the analogy. You also need to clearly connect them to the abstract concepts they represent. If you, the author, don't do this, you risk your reader filling in the blanks and possibly making the wrong connections.

For example, in the Monty analogy, the boxes are clearly described as the variables that store objects, which you create using the equals sign in Python. And the variable name is what you write on the label you stick outside the box.

You may have a clear vision of the analogy in your own head. But you want your reader to have that same clear vision.

Let me finish this section with a link to a couple of other analogies I often use when teaching programming:

• The first one is described in this article: Functions in Python are Like a Coffee Machine. It describes an everyday object—a coffee machine—and maps its features to those of functions in Python.

• The second one uses a story to present the analogy: Understanding The Difference Between is and == in Python: The £5 Note and a Trip to a Coffee Shop.

We'll also return to this last example in the next section about story-framing.

2. Narration through Story-framing

Creating a Narrative Framework for the Technical Content

You can't explain everything through analogies. And even when you can, the description of the analogy is not enough. You still need to write about the technical concepts directly. After all, even if you include narrative techniques, you're still writing a technical article!

Reading technical content is difficult. As authors, we can try to avoid making it harder than it ought to be, but the reader still needs to focus and concentrate as you explain the material. Using a story to frame your technical content can help reduce your reader's cognitive load. This improves their ability to understand and remember the content.

There are two ways in which I frame technical content within stories:

• Framing a single example

• Framing an entire article

Let's look at both of these methods.

Story-framing a single example

The first one is so important for me that it's part of my technical writing style guide I use for every article I write. It's best to explain this using an example.

Let's assume I'm writing an article to introduce the for loop in Python. I am deliberately choosing a fairly basic topic, if you're familiar with programming, so I can focus on how to present the content rather than the content itself.

First, let's assume this is the example I use:

nums = [2, 4, 6, 8]
for i in nums:
    print(i)

This is not an unusual example. You'll find variations of this in many tutorials. However, it doesn't provide any context. As an author, you must work hard with this example to explain why we need to use a for loop and how the for loop works. The reader must also work hard to follow your explanation and understand.

What if I use this example instead:

team_members = ["James", "Ishaan", "Kate", "Ana"]
for person in team_members:
    print(f"Hello {person}. Welcome to the team")

I've replaced a set of numbers lacking any context with a set of names labelled team_members. Even without further explanation, the reader can already picture a scenario where there is a team with four members. It doesn't matter if the reader pictures a sports team or a team of colleagues; they can see this example within a real-life context.

The for loop itself is framed as code to greet the team. The program welcomes each team member. Clearly, you need to repeat the greeting for each team member, which is the whole point of a for loop.

And if you'd rather have an example using integers instead of strings, then you can try the following:

scrabble_word_points = [10, 24, 3, 14]
print("Here are your Scrabble word points")
for points in scrabble_word_points:
    print(points)

As you can see, you don't need to craft a complex story on the scale of War and Peace. A simple narrative to frame your example is enough to make a difference.

Story-framing a whole article

I mentioned earlier that there are two ways I use story-framing. The second technique is to frame an entire article within a story, not just a single example. The case I'll show you next goes beyond this and frames a series of articles, not just one.

I'm currently writing a series of articles about object-oriented programming in Python. This is not a small topic, so I knew I'd need to write several articles. At the brainstorming stage, I was looking for narratives I could use to frame this series of articles. In the end, I settled on Harry Potter.

I divided the content into seven articles since there are seven books in the Harry Potter series. Each book in the original Harry Potter series represents a year at Hogwarts School of Witchcraft and Wizardry. Therefore, I framed each of my articles as a year at Hogwarts School of Codecraft and Algorithmancy. The students are learning object-oriented programming at my Hogwarts, unlike in the original books where, I'm afraid, programming wasn't on the curriculum!

The main parts of the article still focus on technical Python. The story mostly comes in at the beginning and end of each article. However, the examples I use in the articles are also linked to this overarching narrative. So, we create classes called Wizard and Wand, and we have methods such as cast_spell().

These choices have no impact on the technical aspects of the articles but make the material easier to follow and learn.

Why story-framing helps

Both types of story-framing can reduce the learner's cognitive load, especially the extraneous load—this is the cognitive load brought about by how the information is presented. Here are some ways story-framing can achieve this:

• Stories provide context: By adding context to the technical explanation, the reader can understand why and when to use the techniques described.

• Stories increase engagement: People engage with stories better than with abstract content. The increased engagement can help the reader maintain a longer attention span and retain the information better.

• Stories aid information organisation: The brain needs to process and organise new information. A narrative structure can make this step easier.

• Stories provide memorable anchors: A reader must recall the information they learn. Facts aren't easy to recall. The story provides anchors that the reader can use to recall the information.

In the earlier section about analogies, I linked to an article about the difference between the keyword is and the operator == in Python. I linked this article in the previous section as it focuses on an analogy, using a £5 banknote to explain the difference between the two operators. I could have simply talked about a banknote without providing any further context.

However, I also framed this analogy within a story. The story talks about the time I met a friend at a coffee shop. It describes our interactions with the barista and a £5 note we spotted on the floor. The story is not required to make the analogy work. But it strengthens the analogy by emphasising the difference between the value of the note and the actual, physical note through the context presented by the story.

3. Narration through Technical Detail

Incorporating Storytelling Techniques when Describing Technical Detail

The final category is probably the hardest one to describe. It's also the hardest to implement. In this category, we're no longer creating a story in the conventional sense, as we did with analogies and story-framing. Instead, we'll try to make the technical details narrate their own story.

Eh?!

Let me start with an example. I'll get back to what the last paragraph means later.

I'll use the topic of defining functions in Python as an example. And specifically, I'll focus on how variables defined within the function are local variables. Oops! I should have given a "spoiler alert" warning!

I'll pick this up from the point when I'm adding a variable to a function I've just defined. The function is add_numbers_incorrectly(), which tries to add two numbers together but struggles to get the correct answer. This is the code we have so far:

import random
​
def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)

Here are two alternative versions of how the article could explain what comes next.

Version 1

The variable result you create within the function is a local variable. This means it only exists within the function and cannot be used in the main program. You can confirm this with the following code:

import random
​
def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)
    
print(result)

This code gives the following NameError:

Traceback (most recent call last):
  File ... line 6, in <module>
    print(result)
NameError: name 'result' is not defined

You need to return the value within the function. Let's add the return statement and call the function to confirm that this change is what's required:

import random
​
def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)
    return result
​
result = add_numbers_incorrectly(3, 6)
print(result)

This code gives the following output:

12

However, note that there is a random component to the value output.

Let's look at the second version before I comment on the first one.

Version 2

Let's test this function to see whether it works as intended:

import random
​
def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)
    
print(result)

This code doesn't work. Here's the error we get:

Traceback (most recent call last):
  File ... line 6, in <module>
    print(result)
NameError: name 'result' is not defined

This error seems bizarre since it's clear that you defined result on line 4, but the code still complains that the name result is not defined on line 6.

Perhaps it's because we haven't called the function yet? Let's fix this:

import random
​
def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)
​
add_numbers_incorrectly(3, 6)
print(result)

You call the function before trying to print the result. However, you still get the same error message you got earlier. This is because when you define a variable within a function definition, that variable is a local variable. This means that it only exists within the function, and it's not available in the main part of the program.

You need to explicitly return the value at the end of the function definition:

import random
​
def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)
    return result
​
add_numbers_incorrectly(3, 6)
print(result)

The function now returns the value you get from the bizarre addition in the function definition.

However, when you run this code, you still get the same error you got on the previous two occasions. There's one more part to the puzzle.

The return keyword doesn't return the variable. Instead, it returns its value. Therefore, the variable result still doesn't exist outside the function. However, the function returns the value resulting from the addition. You can assign this to a variable in the main scope of the program:

import random
​
def add_numbers_incorrectly(first, second):
    result = first + second + random.randint(-5, 5)
    return result
​
result = add_numbers_incorrectly(3, 6)
print(result)

Now, you create a new variable result in the main program and assign the value returned by the function. Finally, you have an output printed by this code:

12

Note that there is a random component to the value output.

Comparing the two versions

I'm sure I was biased and made less effort with Version 1 when I wrote these! But this won't change the key points.

In Version 1, I give you, the reader, the key result right away: variables created in a function definition are local variables. I still show you the error message, but you were expecting it.

The final segment in Version 1 adds the return statement and the correct function call. They style is to tell you what you need to do and then show you the code. These paragraphs in Version 1 show you how returning values from functions should be done. What's wrong with that?

Let's look at Version 2. I don't tell you what the problem is right away. In fact, I don't even tell you there's a problem. I write some code and run it. This is when you discover there's an error. You're now curious why this didn't work. So I offer a key bit of information: variables defined in function definitions are local variables.

However, the following code snippet still doesn't show the whole truth. I add the return statement in the function and nothing else. But you still get the same error. You're puzzled. Like in a good murder mystery story, you solved a part of the problem but discovered there's more.

So I guide you to look for the next clue: the function isn't called. I add the function call to the following code segment but without assigning its return value to a variable. I'm slowly revealing the whole truth, bit by bit. You, the reader, are more aware of what you're reading since you're surprised by the results. It's not what you're expecting. You're not reading these paragraphs passively, just absorbing information. You're engaging with the content, trying to figure out what's still missing.

Finally, I have the final reveal—assigning the return value to a variable.

In the first paragraph of this section, I wrote that "we'll try to make the technical details narrate their own story". Version 2 creates a narrative through the way it gradually adds bits to the code without revealing the whole truth straight away.

I'll reuse the analogy of the murder mystery story. Version 1 starts by telling you who the murderer is and then explains how the events leading to the murder unfolded—that's not a fun murder mystery to read. Version 2 doesn't spoil the story and has twists to the plot. This is an example of narration through the technical detail itself.

Bonus Content: The Narrative Writing Style

There's a fourth narrative pillar I use in my technical writing. This focuses on the language style itself. Read a typical technical textbook, such as Principles of Optics, and compare the language used with that in a good novel. The style of words used is different. So is the sentence structure. In a story, the author can use sentences of different lengths to set a rhythm to the text, for example. And punctuation marks, well, punctuate the reading. As an author, you can use these tools to guide your reader through the article at your chosen pace.

People default to a narrative style when talking informally, such as with friends. We've already seen how we've evolved to prefer narration and storytelling. When writing technical articles, I try to picture myself sitting in a quiet, cosy coffee shop with a couple of friends.

Imagine I meet a friend over coffee who happens to be learning to code. After a bit of chit-chat, he asked me to explain functions to him. Here's the conversation we did not have:

"Joe, functions are an important topic in programming. It is possible to create blocks of code that can be reused flexibly.
Over the next 30 minutes, I'll teach you:
One. How to define a function
Two. How to include arguments
Three. How to return values
By the end of this half an hour, you'll be able to define your own functions."

You wouldn't think it's strange if the text above was the introduction to a written technical article. But it's not very plausible in the context of a chat with a friend over a hot cup of coffee.

Why not shift our technical writing further towards a friendly and relaxed conversational style? Of course, there are still differences between a written technical article and a casual chat. But that doesn't mean we can't use a more conversational tone and style when we write. This helps our readers engage with the content, understand it better, and be able to recall it in the future.

Final Words

It's not always easy to deviate from the norms. Technical writing often sits closer to the formal, academic writing end of the spectrum of writing styles. Over the years, I have questioned this style, at least for my own writing. If the purpose of writing a technical article is to engage the audience and make it easier for them to understand and recall the key points, why not use the tried and tested techniques that storytellers have been using for millennia? Don't we share the same aims as creative writers?

I'm not advocating that everyone's technical writing should be steeped in storytelling. Not all my articles are stories, either! And when I use storytelling techniques in an article, I'm cautious not to overdo it.

Of course, storytelling can be used to mislead. There are plenty of examples of this in history. But this risk is much lower when writing about technical content. If you trust the author, you can let them take you on the journey they crafted for you.

And I'm still exploring and experimenting with what works and what doesn't, testing the boundaries. This article is a snapshot of my current views on narrative technical writing. Like all my views, they can, and likely will, change over time.

I plan to write regularly about my thoughts, views, and experiments in narrative technical writing. There's a lot more I'd like to say about all the topics I introduced in this article. So, stay tuned!

Should you use narrative techniques in your technical writing? That's not up to me to tell you. We all have our own style, and storytelling doesn't necessarily suit everyone. If you choose to go down this path, you must be ready to break some of the classic rules of technical writing. Not everyone will be comfortable with this. Personally, when it comes to technical writing, I'm happy to be breaking the rules.

More Reading on Storytelling

You can find literature reviews on the science of storytelling here:

• The Storytelling Brain: How Neuroscience Stories Help Bridge the Gap between Research and Society

• Who doesn't love a good story? — What neuroscience tells about how we respond to narratives

• Using narratives and storytelling to communicate science with nonexpert audiences

• The Science of Storytelling by Will Storr

• …and I'll be sharing more from what I read and learn from books and papers in my new Substack: Breaking the Rules. I'll use this space to journal my views and thoughts about narrative technical writing and chronicle my experiments with storytelling. I want to document my evolving ideas on narrative technical writing. You’re more than welcome to glimpse into my thoughts by subscribing to this Substack. The introductory post is here: Are You Ready to Break the Rules?

This was a guest post from on . You can find Stephen at where he shares his hard earned knowledge on everything about Python. Subscribe to his substack to get the best of his writing.

Share The Tech Writers Stack

The main purpose of technical writing is to produce in the reader a new level of understanding —as opposed to, say, creative writing, whose main purpose might be to entertain or inspire, or political writing, whose main purpose might be to make the reader sympathetic to some cause. Almost everything you read in this blog, including this post, is an example of technical writing.

Since technical writing is about understanding, the process of writing should focus on truthfulness and clarity, while being inspiring and engaging. In this post, I’ll show you a loosely defined process that I follow to achieve those objectives in my writing, which I find makes it easier to write often.

The gist of the process is to disentangle content from style. Here’s a TL;DR of the whole process:

1. Brainstorm the main ideas to talk about. These are short, unstructured blurbs of text that encode the main takeaways you think the reader must understand to completely get your message.

2. Define the main talking points, claims, arguments, and evidence for each of those ideas. These might include factual information, data, anecdotes, or well-crafted arguments.

3. Structure the content by reordering the ideas, taking points, evidence, and arguments, in a logical way. This includes adding sections and subsections to bring structure to the article.

4. Draft the first version of your article by expanding talking points into full-blown paragraphs, connecting the ideas. At this point, quantity beats quality.

5. Simplify that first draft by removing all unnecessary boilerplate and repetition and rewriting the text to make it simpler. You should aim to cut between 1/3 and 1/2 of the content.

6. Polish the style of that second draft by changing bland and dull phrases with crisp and engaging writing.

And that’s it. Once you’re done with step 6, you’re ready to publish.

In the rest of this post, I will motivate why this process is useful, then I will detail each of these steps, and finally, I will give you some concrete advice on improving the quality of the content, the clarity, and the style of your writing.

Subscribe now

Why technical writing is different

Technical writing is a form of communication used to explain complex topics clearly and concisely. As in any form of writing, there are basic linguistic and stylistic considerations that you should follow, the most important being clearly defining your target audience. Only once you know who you’re writing for you can decide the tone, style, and depth of your content.

However, there is one way in which technical writing is special. As I said in the introduction, the purpose of technical writing is to produce a form of understanding in the reader. This means there is something you know, and you want to transport that knowledge into your reader’s mind. The problem is the things that you know are not separated in your brain inside a single file that can download. No, they are interconnected with everything you know.

Thus, technical writing involves this process of taking an amorphous web of interconnected ideas inside your brain and transforming it into a neat package that can be delivered with laser precision to your reader’s mind, so that it becomes an amorphous web of ideas interconnected inside their brain. Like a pill, technical writing consists of a core set of clearly defined ideas wrapped in a nicely digestible envelope.

Types of technical writing

Technical writing encompasses three main types: informative, didactic, and argumentative. Informative writing focuses on providing factual information on a given topic. Didactic writing is more focused and instructional, usually providing instructions or describing the process to do something. Argumentative writing is slightly different in that it uses facts and evidence to make a case to try and convince readers of a particular opinion.

Depending on the type of article you’re planning, some details of the writing process will change, but the general workflow I explain in this post works for any type of technical article.

Informative articles are designed to impart factual information without any bias from the author, allowing readers to form their own opinions. This type of article covers a variety of topics, from news stories and current events to historical accounts. By presenting facts in an unbiased fashion, these articles help readers to make informed decisions and develop their perspectives.

Didactic articles are designed to make readers learn something new. These articles can cover a wide range of topics, from deeply technical algorithms to broader technologies. The key characteristic of a didactic article is its ability to present complex information in an organized, effective way. This often involves providing examples and visualizations to help the reader understand the material, as well as utilizing analogies and intuitive explanations to make the material more accessible.

Argumentative articles are the most opinionated and persuasive pieces of writing; they are designed to convince readers of a certain point of view and to argue in favor of a specific opinion or against another opinion. To achieve this, argumentative articles are usually written as essays that contain logical arguments that are presented in a way that is easy to understand. The arguments must have a clear structure, each step building upon the previous one to establish a solid foundation.

Choosing what to write about

All writing starts with choosing a topic. In the case of technical writing, that topic is always something that you understand better than your reader. But it doesn’t necessarily need to be a topic you’re an expert on. It can be something you just learned or something you’re working on.

An idea for finding a technical topic you feel comfortable writing about is visualizing your reader as the person you were one or two years ago. Find a topic that you can explain to a one-year-ago version of yourself that would make them understand it faster or easier than what it cost you. In my case, I often write with my undergrad students in mind. I choose topics I think I would be interested in reading about when I was a student. You can also do market research: find what your readers are consuming online, make polls, or ask a few of them directly.

The act of choosing a topic is an exercise in defining your audience. You always write for somebody, so the better you can profile that person the easier it will be to find an interesting topic to tell them about. When you do that, should be able to write a single sentence that conveys your primary objective with this piece of writing. In the case of this post, it would be something like this:

The workflow

The workflow I will describe in this post is based on the premise of distilling what you know down to its core meaning and packaging it in an optimally digestible way. To achieve that, the key principle is to disentangle content from style.

First, you will define exactly what you want to say, and in which order, devoid of any stylistic considerations. That is the core. And then you’re going to massage it, enrich it, polish it, growing an envelope that makes it easy to digest.

Let’s go.

Step 1: Brainstorm

Begin with an abstract objective for your article and a clearly defined audience. The first step is to expand that abstract idea into concrete talking points: the core ideas that you think are necessary to understand the topic.

For now, all you want to produce is a set of short sentences for each core talking point. You don’t want to focus on anything related to the style of the writing, just on getting all the ideas that could be relevant. Do not bother about order or structure, there is time for that later.

Keep in mind that these are claims, not merely objectives. Most people approach this stage of writing by listing questions they want to answer, like “Explain why technical writing matters”. The problem with this approach is that you’re just delaying the actual task, which is getting those answers out of your brain. Instead, you should write your claims as explicit answers to those questions: “Technical writing is useful for understanding a topic better because it forces you to find sound arguments”.

You can start by listing questions, but then you have to answer them. I've found that starting with some loose questions helps mostly when I'm writing a didactic or informative piece. However, when I'm writing the more opinionated kind of essays, I often already have in my mind some concrete claims that I want to inject into the reader.

The best technique I have found for producing a strong core set of ideas is the reverse outline. This works by starting from an unstructured, raw dump of your mind, and distilling it down to concrete talking points or claims. You can do this by just letting your mind run free and writing everything that comes to you about that topic. But I’ve found it’s much easier for me to talk than write, so I’ll record myself talking for 10-20 minutes on a particular topic, speaking my thoughts aloud without worrying about order or structure. It works best if I take a walk and use a recorder app on my phone. After I record the audio, I will transcribe it and go over each paragraph to distill it down to its main idea.

At the end of this step, you should have a comprehensive list of relevant ideas from which you will extract your core claims. This is all you could talk about.

Step 2: Define

Having a comprehensive list of talking points and claims is a good starting step. Now you need to narrow down and refine those claims into well-constructed, precise statements that are backed up with evidence, arguments, and counterarguments, including providing data to support the claims or citing credible sources.

First, you have to cluster and deduplicate the claims, creating a cohesive set of core ideas that are not vague or repetitive. This helps to narrow down your focus to the most important ideas and allows you to present them concisely and compellingly.

Since technical writing is factual, you need to support the claims made throughout the document with evidence and well-crafted arguments. Go over each of your core claims and decide which of them needs further support. This support can come in the form of evidence such as links to reliable sources, citations of experts in the field, or further arguments that bolster the claim. This can be the most time-taking step, especially if you’re writing about a historical or current event.

The type of support for your claims in an article will vary depending on the type of article you are writing. For example, an informative post about a recent news story requires citations, while a didactic post, such as a tutorial on a technique, could be refined with explanatory examples. On the other hand, an argumentative post can be reinforced through logically sound arguments.

At this step, you may decide that some of your core claims are unnecessary or insufficiently understood, and you may change or remove some of them until you are satisfied that everything is well supported. You will also find counterarguments or contradictory evidence for some of your claims, and you will need to decide whether to remove them or to keep them taking into account the new information. These are just two examples of ways in which you will probably deviate from this process, and go back to previous steps.

If your audience is knowledgeable on the topic you are writing about, then the arguments you use should respect their level of understanding. On the other hand, if your audience is unfamiliar with the topic, you should use simpler arguments that are easier for them to understand. In either case, don’t be condescending, explain things as simply as necessary, but don’t oversimplify ideas to the point they become inaccurate.

At the end of this step, you should have a small, cohesive set of core ideas, precisely defined and well-supported, that together will form the core of your article. This is what you want to talk about.

Step 3: Structure

Up to this point, all you have are a set of more-or-less independent claims with all their support. Once the main claims and arguments are in place, it’s time to give some structure to the whole piece. It is only now that you will consider sections, subsections, and paragraphs.

Depending on what you want your reader to focus on, you will order the ideas differently. For example, if it’s a didactic piece, then you will probably want to begin with intuitions that help the reader understand the why before the how. If it’s a more informative piece (e.g., a historical account or a summary of recent events) then you’ll probably want some sort of chronological order. If it’s an argumentative piece, you’ll want to sort the claims so each one is supported by previous claims.

At this point, you may find that some of your claims are not sufficiently developed, or that you’re missing a link somewhere. This might prompt you to go back to steps 1 and 2 to refine your claims. These first three steps can thus be somewhat cyclic. You can brainstorm, define, and structure, just to notice that you missed some key ideas, and then brainstorm, define, and restructure again. Just don’t overdo it.

At the end of this step, you should have a clear picture of the final document layout, the sections, subsections, and the core claims and their supporting arguments in their optimal order.

Step 4: Draft

At this stage, the ideas have all been incorporated into an organized structure that effectively conveys a message. Now, each claim, argument, or point must be fully fleshed out into a comprehensive paragraph. This means elaborating on the points with examples, explanations, and additional ideas, and ensuring the sentences and ideas flow together cohesively. The audience plays a crucial role here. How much they know about the subject will influence how deeply you dive.

Just write. Prioritize quantity over quality.

When it comes to writing, don't become too fixated on adhering to one particular style. Instead, focus on developing your ideas and getting them across. Don't be afraid of using phrases that seem superfluous, as they can often help keep the writing flowing. Don't worry about how the sentences and paragraphs are laid out; you can always go back and refine them later. Don’t worry about verbosity and repetition either, you will come back, tweak, and polish your writing until it is exactly as you want it.

Reusing content from step one of the process can be a useful way to quickly fill up space, but oftentimes the structure you come up with is so different that it makes more sense to start the process again. One possible way to do this is to record yourself speaking and then simply write down everything you said. You could use an automatic transcription tool to do it more quickly.

At the end of this step, you should have roughly 1.5x the amount of content you need, and be satisfied that everything that could be said is in there.

Step 5: Simplify

At this point, you have a first draft with more than enough content. Now it’s time to make it clear. This will be a major edit, cutting down between 1/3 and 1/2 of the word count while improving the quality. If you want to finish somewhere below, say, 2k words then you should begin with 3k or more.

The purpose is to say the same things with the minimum amount of words. Rewrite sentences to keep their gist while removing all unnecessary words. If you manage that, your writing will be crisp and clear. Keep an eye out for throwaway phrases, things like “in order to”, “with the purpose of”, or even full sentences that don’t provide anything new. Cut them shamelessly, they always make your writing more boring.

When in doubt, cut.

Once your sentences are short, clear, and crisp, you can move one level up to paragraphs. Try to make each paragraph begin with a claim or talking point, and continue with supporting arguments. The final sentence of a paragraph can either be a leading sentence, that connects with the next paragraph, or a surprising conclusion that adds a new insight. Avoid ending with a summary sentence unless that summary brings some new understanding.

The best way to spot overly complex wording is to simply read your text out loud. If you stumble on a phrase or find yourself struggling to get the words out, that’s an indication that the phrase is too long or complicated. If you sound dull and monotonous, with all sentences the same length, then your text will be boring to read. You should write as you speak. If it sounds like something you wouldn’t say in conversation, you’ll know it’s time to tweak the wording.

At the end of this step, your article should be well structured, backed by solid arguments, and easy to read from top to bottom. You could end here, but we’ll make one final pass to polish it.

Step 6: Polish

As a final step, you’re now ready to tackle the style. Ask yourself again about the intended audience, are they technically savvy, or are you aiming for a general audience? Are they fine with technical lingo? Ask yourself also about the tone you want. Is it a sober and informative piece, an engaging and optimistic take, a warming invitation to explore a new topic, or a kind of warning?

Consider the feelings you want the reader to experience. Examine the text and make subtle changes where necessary. For instance, replace uninteresting words with captivating synonyms that better transmit the desired emotions. This will help engage the reader and make the text more powerful and evocative. The key is to be mindful of the desired impact and incorporate words that will effectively communicate the intended message. With a little extra effort, the text can be transformed from lackluster to influential, thus ensuring it resonates with the reader.

In contrast with the previous edit, this should not be a wholesale overhaul, but rather a careful refinement of the text, seeking out those few words that will truly bring the desired tone and atmosphere to life. Minor edits can make a huge impact, and when done correctly can even change the entire meaning of a sentence.

And then you publish.

Don’t spend any extra amount of time doing a second round of editing. Perfection is the enemy of high quality.

Final considerations

When I wrote this post, I went into it with a good sense of the structure I wanted it to follow. Thus, I wrote the introduction almost entirely before moving on to the other sections. I added the first three sections when the rest was almost ready because I felt there was a need for some introduction. But I still made sure to continually iterate on the ideas and arguments within each part of the document and I strived to ensure that each one was clear and concise and that I was expressing my thoughts in the most effective way possible.

After step 4, probably not all parts of the article will evolve at the same time. You might have sections that grow faster and arrive at style check while others are still barebone bullet points. That’s fine, too.

This workflow can help you write better, avoid writer’s block, and make a pleasure out of writing. But the end goal is getting the article out there, not getting the process right. Anything that gets in the way of writing is an obstacle, so feel free to deviate as you need. It's okay to adjust it to fit your writing style or any specific needs you may have. Try to be flexible and have an open mind when approaching your writing workflow, as this will help you to create a positive experience.

Asking for feedback

You can ask for feedback at any step of the process, as long as you ask for the exact kind of feedback that is useful.

See, many readers won’t be able to disentangle content from style, at least on a first read, so if you ask them for feedback on the initial unstructured list of claims, they will probably flood you with useless —at this point— suggestions about word choice, grammar, and sentence structure.

The solution to this is two-fold.

First, ask for specific feedback. Instead of “What do you think about this?”, ask specifically about the step you’re in. “Hey, I’m writing a piece on X, here are the main talking points I plan to cover… Do you see anything missing?”. Or, when you’re at step 4, you can ask something like “What is the most boring 20%? What is the 10% that I must keep?”.

The second way is to be selective about who you ask. Some people are better at analyzing factual content and others will be better at proofreading or style check. Don’t ask the same feedback from the same 100 people, since you won’t be able to read it anyway.

And finally, understand that all feedback is optional, and only you know what message you want to get across. Yes, you should pay attention to your readers’ suggestions, because they are the ones you write for. But, if a piece of concrete advice goes against your gut feeling, trust your instincts.

A note on writing tools

You may have noticed there’s nothing in this guide about how to implement something like this workflow. It is purely conceptual. You could do it with pen and paper, a traditional word processor, a specialized writing app, or using an AI-powered writing assistant. That being said, some parts of this process can be aided with the right tools.

A good text editor will let you move entire blocks of text easily, navigate back and forth between sections without having to scroll with your mouse, fold and hide pieces of text when necessary, check grammar and orthography, and add comments that won’t be shown in the final version to guide yourself. All of that will help you a lot.

Likewise, there’s a lot you can speed up by talking and transcribing instead of directly writing. You can transcribe manually, but there are plenty of good enough automatic solutions out there, some even free.

Regarding generative AI tools, there are some controversies but I think you can make good use of them without losing your voice or being disingenuous. This very article has seen maybe 30% of its content go through AI writing tools, but I’ve reviewed every single word and tweaked almost every sentence afterward. I use them to rewrite sentences more clearly, expand on some talking points, suggest claims or ideas similar to the ones I already have, transcribe my audio recordings, extract key claims from longer paragraphs, etc. As long as you are conscious of the process, and you stand by the final text, I would call that a fair use.

Recap

Here’s a quick recap of the whole workflow. You start with a nebulous idea in your head, that you need to distill down into concrete talking points. Then you will review, refine, and support those talking points with evidence, arguments, and citations until you’re satisfied they stand on their own. Next, you will sort and cluster them to thread an outline that connects all the dots and fills in the gaps. Then you write, as much as you can, without worrying about quality. This is your first draft. You wrap up by making exactly two passes: a long and careful edit to simplify the text as much as possible, and then a quick polish pass to tweak here and there and find the exact tone you want.

The main takeaway of this article is to separate content from style as much as you can. Decide what you want to say first, and then how you want to say it. That’s the key to high-quality and scalable technical writing. The rest is up to you, go find your voice and rhythm.