A blog post about blog posts

Blog posts are everywhere — you’re reading one. This particular blog post gets meta and focuses on whether to, why to, when to, about what to, and finally how to write technical blog posts ✨. Whether you’ve written before or not, this blog post is designed to equip you with useful skills for writing blog posts. You don’t need any special knowledge or equipment to follow along. First we will set the scene by discussing the ramp up to writing blog posts and then we will explore every step of the writing process from start to finish. So without further adieu, let’s dive right in.

Who writes a blog post

Virtually anyone. The internet is a big space. You essentially cannot escape people telling you what they think. So don’t let people escape you when you have something to share and could help others with what you know. Anyone can cook and anyone can write a blog post.

Ratatouille’s Remi thinking about cooking

Why write a blog post

So now that it’s clear that you can write, let’s consider 10 good reasons to write (this is a non-exhaustive list):

1. It’s fun

I like writing, always have. If you enjoy writing as much as I do, why not try doing it with a bit of technical content.

2. You learn new things

Have you heard of talk driven development? That is when people sign up to speak at conferences about something they don’t know yet! These people use writing as an opportunity to make themselves learn something new. Blog posts function in a similar way. If you’re deadline driven, all you need to do is to announce that you will publish a blog post 😉.

3. You learn things more deeply

Working on projects is a great way of learning. However it is very easy to skip some of the learning. At least I definitely find myself copy pasting things and if they work, it’s less pressing for me to figure out why they work. So writing about my projects makes sure I actually understand them better.

When I was in university my professors used to say that you don’t really know something until you’ve had to teach it. That is because having to teach something makes people learn every bit of what they’re teaching, either in advance or when their audience starts to ask questions.

4. You retain more of what you learn

This one is a simple benefit of repetition. If you repeat something more often you’re more likely to remember it.

5. You share your knowledge

You get to help people learn and grow which is incredibly rewarding. That by itself is a great reason to write. Whether it’s for beginners or advanced techies.

6. People see your blog posts 👀

This is sort of the instagram reason of writing and links closely with the next reason.

7. It can help your career

If you put yourself out there, people will see you and that has advantages. Technical writing is required of almost any software engineer to some degree because every team needs some level of documentation around their tools and code. With your writing, future employers can get an indication of how you think and how you explain things which gives you a chance to shine. Having your writing out there may also result in interesting positions finding you.

8. Good for developing your personal network

If people see you writing blog posts, they’ll start to know your name as a subject expert, follow you on Twitter, etc.

9. It is an alternative to public speaking

If you would like to share your knowledge but are afraid of the stage or still working towards taking the stage (which is both totally valid), blog posts are a similar way of sharing but without you seeing your audience directly. They will still get to meet you and learn from you through your writing. An additional advantage is that they can learn from you when it’s most convenient and relevant to them and they can always come back if they want to.

10. Opportunities for some extra 💰

There are companies that will pay you for your writing. If you’re a student and are looking for some extra cash on the side, this could be a job that allows you to do something relevant to your degree while earning some money 🙌.

When to write a blog post

Write when it suits you to write. Many people don’t write blog posts until they’re looking for a job. That doesn’t have to be you. It’s your free time and your knowledge, you set the rules. You can write when you’ve learned about something or when you want to learn about something. You don’t need to already know about a subject in order to write about it — it’s perfectly valid to learn while writing. In fact this gives you the opportunity to write down all the questions you have and answer them in your writing. If you know a subject already you may be more biased in assuming that some parts are ‘obvious’ and you will have to work harder to ensure you cover everything. So anytime you have time and want to write is a good time really.

What to write a blog post about

Have you found something people don’t seem to know about or don’t find obvious? Help them on a broader scale. If you find yourself repeating advice or explanations a lot, this is a good indicator that you could write about it (that way you can also afterwards just share a link whenever someone asks).

If not that, ask yourself what younger you from a year (or a month) ago would have liked to read a blog post about.

Don’t get discouraged if someone else already wrote about the same thing or a closely related thing. Maybe that blog post isn’t as detailed, or maybe it’s aimed at someone else. It’s always good to have multiple resources about the same topic out there! Some people will prefer your style of writing over another’s.

Lastly, just write about something you care about or would like to learn.

How to write a blog post

Finally. Let’s talk about what you really came here for and if you didn’t come here for this and got convinced by the above that’s also 👌. We will assume you’ve chosen your topic and now want to get writing. Let’s go!

Note: This is one way of writing blog posts. It is not the only way you can choose to write. It is merely a helping hand if you don’t know how to start. Feel free to ignore it, tear it apart and put the parts together differently, or use it as is — totally up to you.

1. Your writing environment

It is your choice whether to start with 📜, 📱, 🖥, 💻, or another platform. You do you! Don’t let anyone tell you where to write.

I personally like writing on trains where I have no internet. My first draft is often in plain text or Markdown which I like to write on Atom with my two favorite packages:

  • Octoclippy, a friendly Octocat or Hubot that keeps you company and does funny animations when you save your document.
  • Activate Power Mode, a package that counts your writing streaks and gives you encouragements as you write.
My atom setup with the packages Octoclippy and Activate Power Mode

However, my favorite editor doesn’t have to be yours. Spend a bit of time making your writing environment what you want it to be. It will be worth it.

2. Don’t start with a blank editor/page!

If you start with a blank page it will probably be harder for you to write because it feels like you have no idea how to go from nothing to this great piece of writing you envision. Instead, try one of the following approaches:

Use a blog post wireframe like this one:

A gist with a copyable template for a blog post

Or:

  • write down random bullet points of things you would like to mention in your post
  • start by drafting an outline
  • write down a list of the questions you get asked about the topic or would have once asked yourself

If you start in these ways you will have something to guide you while writing and a place to keep to-do’s — would recommend. After this brainstorming session you should have some assembly of thoughts written down.

A screenshot of the outline and thoughts that were the beginning of this post

3. Starting to write

Trick headline. If you followed step 2, you already started to write! You’re doing so well! 💯🔥

Depending on how you chose to start you will either have a random assortment of thoughts about things you will want to mention or you will have a nicely structured first outline. The next step is to create an outline with bullet points/random thoughts about what should be in each section, including code snippets (if applicable).

Don’t feel like you need to stick to your outline at any point, if you feel you need to change anything, change it.

A screenshot of this blog post at the stage of it being a structured outline with notes

At this point you have a structure and some ideas for each section which means you are at about 20%-30% of the blog post process — well done! Now (or potentially after the next section on targeting) is a great time to show your thoughts on the structure of your blog post and the concepts you will cover to a first reviewer. They can give you feedback on whether the basic structure makes sense to them and whether you are covering the right bits.

4. Targeting your writing

While writing, you should always keep your audience in mind. In the intro you will want to mention your target audience so that readers are aware whether they are in the right place! Knowing you’re in the right place is very important for an audience that just committed to reading your work — nobody likes spending time reading a post just to find out it wasn’t the right thing for them.

Throughout your post your knowledge of the audience will inform your style of writing, as well as the level of detail you choose to incorporate. If you’re writing for students, you will likely use a different style than if you are writing for bankers. Similarly you will likely want to go into more details on setup and give more information on steps if your audience has less experience.

Less experience. This is a difficult concept. It’s very hard to establish a common ground of technical knowledge between everyone in your potential audience. My rocket science could be your walk in the park — so you shouldn’t assume people will be familiar with the technologies you are. Again, it will pay off to mention in the beginning what level of experience and which tools you will expect people to know to be able to follow along.

When in doubt, it is always better to include too much rather than too little detail. If the content is well structured, people can skip the bits they know. On the other hand, people who don’t know these details can read them and not struggle and give up because of an assumption that ‘everyone knows X’. Later in this post, we’ll talk about GIFs and Screenshots which are an especially great way of packaging a lot of setup information in a nice, clear way. They are easy to skip, yet will help people with less experience a lot.

So for now, think of how you want to write and decide on an audience and outline this audience in your intro while setting the expectations as to which knowledge and tech stack is required to follow along. If needed, add a section below your intro for requirements.

A screenshot of the beginning of this blogpost with the emphasis on the third sentence where the target audience is described

As you continue, keep this audience in mind and try to put yourself into their shoes.

5. Voice

Your blog post can be as formal or informal as you want it to be. This is your voice you’re using to explain a topic and your way of writing is part of how you choose to portray yourself. Whether you include memes, emojis, etc. is up to you — or up to the company’s voice guide if you’re writing for a company. Generally it seems to me that people prefer to read less formal writing, meaning shorter sentences and not the type of words you’d use to impress your former (or current) teachers. People should focus on understanding the technical contents of your blog posts — not your language.

Other things to consider:

Active Voice. Use active voice as opposed to passive voice, i.e. “Nexmo sends a request to our webserver” rather than “a request is received”. Active voice ensures that the actors are identified and it generally leaves less open questions. The exception is if you want to emphasize the object of the sentence.

We all know that we don’t know everything. Using phrases like ‘Obviously…’ or ‘As I am sure we all know…’ can make people uncomfortable if they don’t know the thing that you claim is obvious, especially in a technical context. These phrases don’t add anything to your content — so try to exclude them.

s/he/they/g. This is an expression that will replace occurrences of he with they if used in a text editor like vim. Try to be inclusive and mix up genders. If you use ‘he’, mix it up and use ‘she’ as well (or better even: use the singular they which is gender neutral). Apply the same to words like guys (e.g. engineering guys). Replace them with neutral words like programmers, or folks, or humans. If you need inspiration or more information about this, check out inclusivewords.com. Try to also vary your examples: maybe the CEO in your blog post could be Jenny and not Steve or just an ambiguous name like René. The reason this is important is because you’re speaking to a broader audience whose way of thinking you will influence whether you’re aware of it or not. So give the language you use a thought.

Try and come up with a small style and voice guide for yourself and then stick to it while you continue writing your blog post. If you want more inspiration, consider the Mailchimp Content Style Guide and the 18F Content Guide. They are great assets to read further into.

6. Filling in the gaps

By now each section of your writing should have bullet points and code snippets on what it should contain. In this step you will take your bullet points and turn them into text. Ideally, you will want to wrap your whole blog post into a story or timeline. This allows readers to follow your content more easily. The blog post you’re reading is trying to show you how to write a blog post, after hopefully convincing you that you are the right person to write.

As you transform your bullet points and code into a complete text, you will want to research bits that you don’t know and think about how to make it easy for the reader to understand. Focus on what you want the reader to learn and what information will help them most. When giving readers code, try to explain difficult logic or concepts and what each bit of code does. This will be easier if you have broken the code up.

While wrapping your content into a story you may find yourself talking about your achievements more than giving actionable advice. If that happens, try to get to the bottom of how you achieved these achievements and break this process down, then focus on the process more than on your personal achievement. You can, of course, mention your own story elements if they fit — which will depend on the context. If your blog post has a more autobiographical nature, then ignore my comments. However in my experience most technical blog posts will not be of autobiographical nature.

A screenshot of this post as it has become text and is nearing the finish line.

With all the actionable instructions and advice you’re giving, you will want to make sure that as people carry out each action/step, they stay engaged and can ideally tell that they are doing it right. You can do that by making the steps small and the goal very clear and, if in code, by giving people tests of what they should be able to do after each step. This will ensure that people know how to tell if they have achieved what they were supposed to in each step and it will give them a wonderful feeling of having accomplished something good. These ‘oh it’s working’-moments will encourage people to continue and reassure them that they’ve got this. For people that get lost or confused, it’s great if you offer the full code for each section.

Did you notice that we jumped right into the writing bit and started explaining how everything worked? We shouldn’t forget to document our setup! Are you using Python2 or Python3? What frameworks are you using? Which APIs? How do people sign up and install everything? You will want to make sure to document your setup clearly. Here GIFs will work absolute wonders as they can show long processes without a wall of text. The gif below shows the relatively lengthy process of creating keys for a Microsoft API. We will go through how to create these GIFs later. However, you should already know that GIFs should always come with good alternative texts that fulfil the same purpose as the GIFs to ensure maximum accessibility.

An illustration of a long sign up process for a Microsoft API

After you document your entire setup, it is a good idea to start from scratch and follow your own instructions to make sure that everything works (if you can, try to consider different environments in your instructions or try to give people an online environment, like glitch, that will work the same for everyone).

After working through this section you should have a complete text with actionable advice and instructions using small steps and clear goals with plenty of ‘yay it’s working’ moments. You should also have a clearly outlined setup. Great work!

7. Polishing

Now that you’ve written your blog post almost completely, it’s time to polish off any rough edges. Read over it a few times and put on the hat of a reader. While doing so, ask yourself:

  • Am I telling a coherent story? Your post will be easier to follow if you tell one story and fit your content along that story line. Explain where you’re starting from and what the problem you’re addressing is. Use this background as a narrative to structure your content. The story will allow you to make sure that every step brings your audience closer to a goal.
  • Do I introduce hacks? If you know something you are doing is a hack — try hard to avoid this hack. Describing somewhere in a side note that what you’re doing shouldn’t be done on production is a start but the chances that people will not see the note or ignore it are high. If you have to introduce hacks point them out within the code and give the reader an idea of how to fix it or add links that inform people how to fix it.
  • Am I missing steps? Follow your entire process once more and test it to see whether you missed something. It’s hard to notice this until you actually force yourself to follow all your steps as written down.
  • Is my beginning catchy and concise? The beginning paragraph is where your readers will decide whether to navigate away or whether to give you their undivided attention. You will want to make clear who your audience is and what you’re offering the reader. Additionally, you’ll want to keep it brief, otherwise you run the risk of people not reading everything and instead just glancing at bits.
  • Does my ending have a call to action? What do you want people to do after they read your blog post? Reach out to you with questions? Read other blog posts? Work further on the contents of the blog post? These are some options of what you may want as an outcome, but for each of them you should give the reader a slight nudge into the direction you’d like them to go. You can do this in several ways, for example by giving your contact details, linking to other content, or giving ideas on possible extensions of the project.

During this polishing stage don’t worry if you find yourself going through some of the previous steps again — that is perfectly normal. When I write I tend to have a todo list at the end of my post and work on that as I am progressing.

A graphic that illustrates that you can move from any step back to any previous step

8. Tips and tricks and throughts

Code Snippets

Make sure to include code snippets when you’re doing a technical blog post that requires them! Ideally with syntax highlighting. Break your code up and explain each section. Doing so will make it easier for people to follow. If possible also provide a link to the full code for people so that they can see how the pieces fit together.

A gist with a code snippet with syntax highlighting that merges content and code into a blog post

Screenshots 📸

Use screenshots! They’re great to break up huge chunks of text and to help your audience follow along. As you do this, it’s a great improvement for accessibility if you provide good alternative texts for your screenshots and GIFs, so that people who cannot see the images can get the same information.

Use GIFS

An illustration of the usage of GIFs

But how I hear you ask! First, I used the preinstalled QuickTime on my Mac (if you’re on a different platform please Google what the best option is as I am not an expert in how to do it elsewhere 🤫).

A screenshot of the QuickTime menu for making screen recordings

Unfortunately the only thing it won’t let me record is how to use it. So if you want to see how to do that watch this video here.

QuickTime will output a video of your screen recording which you will then have to convert into a gif. I would recommend using ezgif.com for this. See below the entire process of converting it and speeding it up! The speeding it up is mostly so that I don’t have to bore you with my slow typing and menu interactions. It may also be because I am a little concerned with how slow I am…

However, while GIFs can be great, please create alternative text so that people who cannot benefit from the GIFs are also able to follow the steps.

A GIF that shows the upload process for a video, which is then converted into a GIF and sped up

To link or not to link

Experienced blog post folks say that every link in your blog post can mean people leave your post and never come back. A way to avoid people going down rabbit holes in your post and not coming back is to have very few links and to ideally place them at the end.

It can however be helpful to link to tutorials that cover bits that you don’t cover which helps out beginners in particular — so it’s a difficult choice. As you see in this post I try to have few but helpful links where I consider them needed.

Teachable Moments/Tips

You very likely have workflows that quite a few people around you don’t have and would love to hear about. Maybe you use a tool called TextExpander to turn small commands like addr; into your address or maybe you have a copy-paste-clipboard manager that allows you to reuse and search through things you previously copy-pasted. Each of the people who introduced me to these things thought of it as completely normal and commonplace. Yet both suggestions helped my productivity immensely! The same goes for coding and terminal usage (did you, for example, know that ctrl-u deletes from your cursor to the beginning of the line in a terminal?). So if you use productivity apps or shortcuts while creating your blogpost — give them a quick shout out. Erin McKean calls these moments in talks teachable moments, i.e. unplanned/natural opportunities that offer an ideal chance to offer insight to an audience.

After you write your blog post

1. Reviews

Whether you do or don’t want a review is entirely up to you and depends on your situation. If you choose to have reviewers then you should provide then with a good reviewing environment. Your reviewers should have an easy time writing comments and fixing typos. The by far easiest method I know for this is Google Docs. Within Google Docs select to share your document with the option can comment. This allows reviewers to add suggestions and comments. You can then accept or reject these suggestions and you can comment on issues to discuss them further.

A screenshot of the Google Docs sharing dialogue

When writing blog posts for companies, they will generally be reviewed by the companies themselves of course. If you’re writing professional blog post without a company, you will probably want someone to scan it for typos and grammar mistakes (spell check is also a good friend but not perfect). You may also want someone to proofread your technical content.

Let’s start with typos and grammar. Since everyone reads, everyone who has a good sense of language can give you a bit of feedback. So ask your friends, co-workers, siblings etc. for help! One person is probably enough. Be sure to pay for their coffee next time you see them or otherwise show them your thankfulness ;).

An illustration of the amount of comments left on the final draft of this blog post

For a technical review, you will want to look at someone from your target audience and potentially someone who knows about it already. If your target audience is beginners then asking someone less techy would be a great idea. Thus you can gather their feedback on things that are unclear to them and work on those to make it even better — meanwhile they will gain skills by going through it (it’s a win win!). Asking someone who knows the topic will also be helpful as they will be able to point out things you can improve or maybe explained wrong. You may or may not need both types of review. It really depends on your situation and you will have to be the judge of that.

Don’t feel like you have to get a review if you don’t want to. You may find that people will try to change the voice of your blog post to a way they would do it. Don’t feel obliged to take this feedback. In fact, don’t feel obliged to take any feedback. However, if you find you’re not getting feedback you want to work on you should probably ask someone else next time. Asking for feedback and then ignoring it wastes both your and your reviewer’s time.

2. Publishing and Promoting!

With your blog post reviewed and ready, the next question is how to get everyone to read it. There are multiple platforms you can choose to publish your blog posts on such as medium, Wordpress, etc.. Medium is very easy to use and if you’re just getting started it is probably the right choice. Alternatively you could consider making your own blog. If you’re interested in starting a blog, check out Pauline Narvas’s post about her starting her’s.

Once published, you get to share your work on Twitter, Facebook, Instagram, LinkedIn, and all your other Social Media. I must say this isn’t what I am an expert on. If you’d like to read more, Pauline’s post about starting her blog has a good section on promoting your blog post.

3. Feedback

First of all: CELEBRATE! You’ve done it, you’ve written a blogpost. Lara Hogan says that whenever you achieve something great, you should celebrate this with your own little indulgence. That will make sure that you take the time to appreciate and reflect on your achievements. Her ritual is getting herself a fancy donut. So go get your version of a 🍩!

After you come back you may encounter that the first few people read your blogpost. They can react well or not so well. People can come up with a variety of reasons for not liking your writing. Don’t take it too harshly. If you want to read through the comments, try to filter the constructive bits out. If it’s not constructive feedback, ignore it and don’t engage. You can’t please everyone. I can guarantee you some people will tell me off for writing this blog post because I’ve only written X blog posts. But hey, I never claimed I was an expert. I just hope someone will find this useful. If just one person finds this helpful — it’s a win. Also:

Haters gonna hate

BUT it’s not all horrible — there is also the positive feedback! People who say that they found your writing helpful. That is much more important than any negative feedback. If you can and want to, go ahead and engage with people that comment and answer their questions if you know the answers. Connect with them too! Also if you’re keen, then turn your blog post into a talk and apply to conferences with it. There is also a talk version of this post which which I created for Women in Tech Nottingham.

Conclusion

I hope you enjoyed reading this and have learned something useful. If you have any questions please reach out to me on @naomi_pen or at naomi.codes.

Also if you do end up writing a blog post after seeing this. Please let me know — I promise to share it for you in return 💖 (and it will make my day).

PS: If you’re a student, have a look at GitHub’s Campus Expert Program — they have great resources to learn technical writing and other skills!