Tips for Technical Writing

Do you struggle to write blog posts? Developing your craft when it comes to writing can be as intimidating as the buggiest code.

Refining your writing will be another fascinating challenge on your path to mastery. At its best, writing can be very satisfying. While it might feel daunting now, in time it could become something you take real pleasure in.

Yet it can sure feel difficult and daunting to establish yourself in this space. What should you write about? How should you get started? How often should you publish your work? Where? When?

It's a lot to take in.

This post contains some advice to anyone aspiring to technical writing on the web. Also included are some creative writing exercises to help develop your thinking.

Picking A Subject

It is one of the most normal things in the world to commit to writing a blog post, get excited, open up a fresh new document...

... only to stare at a blank screen for thirty minutes and then quit.

Finding a topic to write about is hard. Going into it without a plan can make it close to impossible.

One of the best places is your own recent history. What you've worked on this week is something you've already got relevant experience in. You're also, if only for a little while, wholly invested in the topic.

With that in mind, here are two good questions to start with:

What's made you excited lately?
What's a technical challenge you've recently overcome?

Keeping a list of these things, as and when they happen to you, can be useful. It is much too easy to forget these little moments, but they are often the very things people most want to read about.

EXERCISE: At the end of each work day, write a quick summary of what you did on that day and how you feel about it.

EXERCISE: Look through your browser history for the last month. Pick out a resource that solved your problem. Why was it effective?

You Are Almost Definitely Your Own Worst Enemy

You've had a great idea. You are bursting with excitement as you sit down and start writing a new blog post. You try and turn all your exciting ideas into words, but it feels like it's going wrong. You can't phrase things on paper like they are in your mind. You lose your confidence.

Sound familiar?

Capturing that "inner voice" with your writing is a struggle. It takes a lot of work and a huge amount of time. Even with years of craft, the voice of your writing might not be what you once imagined it to be. You might have a wholly different voice than the writers you most respect and aspire to be like. In time you will learn to grow into your style.

How you overcome your fear in the meantime is something you'll need to work out. But you should commit to publishing your work when the technical aspects are correct. It's always worth double-checking your source code examples. You may never feel ready, and this is OK.

Consider the Audience

Your audience today might not be your audience tomorrow, which is fine. But your reader is important. Different audiences have different responses. Your style is your secret sauce, but does that style communicate to the audience as desired?

As an example, this piece you are currently reading is being written with brief sentences. The tone is active. It should feel punchy, nippy, and swift. Its goal is to convey a lot of concise information to an audience looking for tips and knowledge. It tries to use short, understandable words and phrases.

It is not written to be ornate, or detailed, or chatty. These things can be fantastic, but it is not the intention of this piece.

EXERCISE: Go through your last few blog posts and make a note about who you intended the audience to be.

EXERCISE: Rewrite an old blog post for a very different audience. This helps you frame your own understanding from different angles.

Set A Time Limit On Your Drafts

You've had a great idea for a blog post, and you start writing up a couple of paragraphs as a draft. The post never leaves your draft folder.

Software is an industry that can attract perfectionists. You might be one of them. You might feel that your writing is never ready for the outside world.

There can be value in drafts. It can be great to get a colleague to read a draft, and then you can make some amends before publishing. It can also be very effective to give yourself an overnight break from a blog post and finish it off with fresh eyes. This is drafting with a purpose, and that's great.

Your drafts are little rockets looking to break escape velocity. They should be free.

Hoarding your drafts is a common mental hurdle, and it can be devastating.

EXERCISE: Try to publish a blog post on the same day each week for a month. Don't beat yourself up if you don't make it.

Separate Publishing And Writing

It is worth considering the difference between writing and publishing. These are different goals.

At the extreme end of publishing is someone who posts an article on Medium every single day, without fail. These articles might lack extensive research, but they likely engage with popular topics. This is a huge skill in itself.

On the other side, those who devote themselves to writing might throw themselves at the form. Their posts might be well researched and very long, but they might also be difficult to read.

Some of history's most intricate and masterful writing is very difficult to read. Is it good writing if it's hard to read? You might have your own opinions on this.

An excessive emphasis on writing might also mean you never feel comfortable publishing. You might always feel your work is not quite ready yet and you need to revise it a few more times.

It might not be a surprise to learn you have to engage with both writing and publishing to get anything done.

Think about your own motivations. What do you want to get out of your blog posts and articles? It's never a bad idea to think about those goals when you start writing any of your articles. Each piece is different.

Take Notes

You might sometimes feel like you're prompted to write about certain subjects. This might feel like an awkward fit at that particular time.

There could be many reasons for this. You could lack confidence in your own knowledge. You could still be developing your opinions on something. It's also fair to admit that you might have nothing to say on the topic, even if you know it. You brush your teeth every day, but could you write 1000 words about flossing? It is doubtful that many could.

But there's no reason why it wouldn't be valuable to take notes on what you're doing. These notes don't have to be very detailed, but they can be precious down the line. They will help you expose your ignorance and share your knowledge.

There are many advantages to taking notes. For instance, you can write your expectations and compare it with reality. It's amazing how valuable this before/after knowledge can be, and how fast the brain forgets it.

Taking notes also helps develop a healthy habit for reflection and mental planning. They help you write articles when you are ready to write them. They help you practice writing and develop your thinking. With notes you don't have to worry shaping the narrative of an article or publishing. They're only notes. Notes are great.

You can also share your notes with a mentor for their guidance. helping expose your ignorance and in time document your own journey. Future You might also find it handy to be able to see what caused problems when you were once in a similar position.

EXERCISE: Spend the first 10 minutes of each day writing down what you did the day before, and what you'd like to do today. Then reflect on it at the end of the week. It can be surprising how useful you find these moments.

Start With A Template

With time and practice you will develop your own style and writing voice, but this is not easy. Relying on an established structure can be useful even for experienced writers. Readers can also find the convention of a good template reassuring and reliable.

Below is a technical writing template, structured into a beginning, middle, and end. These are the fundamental building blocks of any story and remain effective here.

Beginning - What Are You Going To Tell Me

Set up the problem, usually in a couple of short paragraphs. This is a good place to think about the five W's—who, what, where, why, and how.
Try not to make your introduction too long. This is hard. An old creative writing trick is to delete the first paragraph after you finish the whole piece. It is surprising how often that makes an article feel more immediate.
Another nice way to start is using your intro to frame the question your article is going to answer. Imagine you are writing an article on the useState hook in React. Your intro is a good place to set up why you'd want to be doing that to begin with.
Often you may be writing as a way to develop your own understanding. Your intro here gives you the opportunity to lay out your questions.
Your intro is also your "shop window," and helps you develop your own inner voice and personal style. It's also your sales pitch: why should a reader be looking at your explanation of a useState hook?
Consider your audience. You can even say in your intro who this blog post is for. Let's stick with our imaginary React useState hook article for now. Is it designed for people who are hungry to know exactly how it works? Is it for those who use React on a daily basis and want to get up and running in 5 minutes? Is it for someone familiar with another web framework? Is it for a complete React beginner?

Middle - The Telling

This should be the bulk of your work—at least 80%. Your beginning and end should be brief bookends for your main.
This is a great time to look at other sources—especially sources you admire—and how they convey this journey.
Try and go in one direction. Don't ping back and forward in time.
Good code examples can be very powerful. Don't be afraid of using code.
Lists can be a great way to break up text whilst also, you know, keeping it grouped together. This article relies on lists to break up the information.
Think about design and formatting. Try talking to a designer, if you can.
Contextual images are especially effective. They are great for showcasing design, UI/UX, and even quick snapshots of code running. We could use imagery, both static and animated, to show our useState hook running in the real world.
Diagrams (hand drawn is fine, and often preferable) can help convey complex information.

End - What Did You Tell Me

Recap what you've been discussing.
Add some links to further resources—where might someone go if they wanted to explore this further?
Add your conclusion. This can be tricky.

Go Your Own Way

With all this in mind, the most important part of your technical writing is you. Your perspective will be refreshing and unique. Even if your article helps a single person, that's a wonderful way to give back to the community. Chris Coyier nailed the best way to think about it:

Write the article you wish you found when you googled something.

Writing is hard. But your voice is valuable. We can't wait to see where it takes you. 👏