Writing a blog post is an art and a science. I’ve found that having a plan keeps me focused while allowing flexibility to sprinkle in some personality. As I’ve had lots of questions about this recently I’m going to share how I tackle a new post from start to finish.
This was written originally with the folks on Dev.to in mind so references specific tooling used on the platform. If you’d like to get started writing on technical topics Dev.to is a great place to start.
1 – Who Are You Writing For?
To get started, determine who it is you are writing for. Having an idea of your audience is just as important as the topic itself. Even if you are writing for ‘future you’ having that in mind will keep you on track.
- Are you writing for beginners or experienced developers? Try and have empathy for your reader before you start writing.
- If you are writing for experienced developers what do you expect them to already know?
- Consider a series of posts for more complex topics. Your readers will appreciate being able to jump in at any point when they are ready to learn something new.
2 – Build Structure First
Think about the main points you want to get across before you start writing. Putting this down as a base will save you dwelling on any one point for too long. I like to use six or seven headings for my content, an introduction, conclusion and some links which I add when I’m ready to publish.
- Create an outline to structure your post. If you like my structure you can find the template in this gist.
- Think about having several headings, subheadings and maybe bullet points. This not only structures your thoughts but makes it easy for your reader to skim.
3 – Just Write
With your structure in place, you can fill in the gaps with your tips, tricks, and knowledge. This step is the most rewarding as you get all that great information out of your head and onto the page. Set aside an hour or two to research your topic and write your first draft.
- Get your ideas into a Google Doc, text editor or straight into the Dev.to editor.
- Try and write in the same way you would speak to a colleague. Let the approachable nature you have in real life carry over to your post.
- Try to be concise and get the most important talking points down first. You can always add more later.
4 – Edit and Review
Now that your ideas are on paper it’s time to review and edit. This step is all about refining your thoughts and trimming it down. At this stage, it’s important to note you shouldn’t get too attached to what you have written. If it doesn’t need to be there, take it out.
- Ask yourself – does it fulfil its purpose? Is it easy to understand?
- Avoid vague language that tells your reader nothing. How long is a “long time”? How many do you mean by “several”?
- To tackle spelling I like using Grammarly. Just remember you shouldn’t rely on it for all your editing. It won’t catch correctly spelt words that are in the wrong place.
5 – Add Some Visuals
Once you are happy with the general layout and content consider adding some visual elements. This doesn’t have to mean images. You can add code blocks, liquid tags to show relevant posts or even embed tweets. All these extras keep things interesting and save your readers from a wall of text.
- The flavour of markdown Dev uses supports syntax highlighting in code blocks. This makes code easier to read, and more accessible than an image of code.
- Consider creating a flowchart or architecture diagram. This can be done for free in Google Draw and if you’re an AWS user you can download their icons too.
- Free stock images are available on Pexels for images in your post or as a cover. The best size is 1000 x 420 so keep that in mind as you are cropping. Don’t forget to show your appreciation by crediting the creator!
- Canva is another good option if you are feeling creative and would prefer to build something original.
6 – Leave Overnight
You’re almost done! Congratulations on getting this far. Now it’s time to sleep on it.
Having some time away from your post allows you to do one more edit with fresh eyes. You may spot a typo you didn’t see before or decide to rearrange your points so it flows better.
- Don’t get carried away and go from zero to published in one day.
- Read your final draft aloud to test sentence length and remove unnecessary words.
- Think about how you would respond if you were reading this post. If you have would have questions, think about answering them for your readers.
7 – Tell the World
Now that your work is done and you’re ready to publish, consider how you will let the world know about it. This will help get your post out there and build your personal brand.
- Share your post on your favourite social media networks – Linkedin, Twitter, Reddit, HackerNews or in a Facebook group.
- Make use of the tools here on Dev and “Suggest a Tweet”. You may be tweeted by the main account or one of the topic-specific accounts.
This is the process I go through each time I write. It allows me to collect my thoughts, keep my reader in mind and stay on track.
I’d love to know the process you go through as you write. Do you have a process or any tips to share?