My top 7 tips for engineers who want to write their first blog post
Tags: writing, beginners, learning
Published: 2024-06-04 11:17:45

I kicked off my career journey as an IT project manager, but my curiosity led me down exciting paths into coding (especially front-end and iOS) before moving into journalism.

Over the past 6 years, I've had the pleasure of supporting numerous developers and engineers in French tech companies with their blog writing initiatives. From polishing up posts to collaborative writing sessions and even crafting pieces from scratch based on their ideas, I've been there every step of the way.

Now, let's jump right in! Here are my top 7 tips that I love sharing with the developers and engineers I work with.

## Sharing is a state of mind

Finding inspiration for blog post topics can strike at any moment, so it's wise to capture those ideas as they come. Whether you're brainstorming during lunch, in a meeting, or even in the bathroom, write down those thoughts promptly. Personally, I rely on the Notes app on my iPhone, but use whatever tool suits you best. The key is accessibility, ensuring you won't forget those creative sparks. Then, when it's time to write, you'll have a ready-made list of ideas to choose from.

Once your post is written and published, your work has only just begun. Especially if you're not yet a household name in the developer world, sharing your post is crucial. Whether it's on social media, through a newsletter, or on a content curation platform, getting your work out there matters. If social media is your choice, adding a personal touch to the link can make all the difference in engagement.

But don't stop at just sharing — leverage your research and writing efforts further by responding to Calls for Papers (CFPs) and offering talks on the same topic. Adapting your article into a presentation may require some additional effort, but it's far less daunting than starting from scratch. And remember, it goes both ways — your talk can inspire your next written piece just as your article can fuel your presentation.

## Understand your audience

Before you start writing, think about who your readers will be. Are they beginners, intermediate, or advanced engineers? Tailor your language, content depth, and examples to suit their understanding level. 

When writing for beginners, it's important to use clear and simple language. Avoid technical jargon and explain complex concepts in a way that is easy to grasp. Additionally, provide plenty of examples and visuals to illustrate your points.

Using visuals and code examples benefits everyone because it helps visualize abstract concepts and understand them more easily. It also caters to different learning styles. Some individuals are visual learners, meaning they learn best through images and diagrams.

## Topic !== angle

An article cannot cover all aspects of a topic. Attempting to do this could result in a 5,000-word post that would be difficult to read. In order to tackle your topic effectively, you must choose an angle — and stick with it!

To illustrate this, let’s take a concrete example. If you want to discuss Python testing in your post, for instance, the angles could include:

- The historical angle: Tracing the evolution of Python testing methodologies over the past decade.
- The practical angle: Tips for testing Python code effectively.
- The feedback angle: A journey through the Python code testing methods used in your company.
- The news angle: Spotlighting the newest libraries and tools designed for testing Python code.

Some people put everything they can think of in their blog posts without considering an angle. They think more is better, but it doesn’t work like that. Others tend to systematically select the same angle: the feedback approach. Well, sometimes it’s the best angle to use to tell a story, but not always. Considering the angle before you start writing will save you a lot of time and make your post more engaging.

## Be explicit

Imagine picking up a piece of string that symbolizes your thoughts and holding it tightly in your hands while writing the blog post. And don’t drop it!

You should always ensure there’s continuity in your writing. Whenever you switch between ideas, you must clearly explain why. E-v-e-r-y time. Reading your text out loud can be very helpful with this. It allows you to identify gaps in your thought process or missing information.

And since it is the first thing your reader will see after the title, the introduction to your blog post should be the most explicit part of all. Make sure it provides some context, as well as an explanation of who the target audience is, why you have the authority to write it, and what the reader should expect to find in it.

## Spend time on your headings

Your blog post’s title will be the first item readers will notice. This is what will make them click on your article (or maybe not!). It is so important that finding the right headline should be a separate step in your writing process. You should spend time on it and involve your reviewers in the decision making. To brainstorm titles, tools like ChatGPT can be very helpful. My recommendation is to put forward three to five proposals for your reviewers to choose from.

Subheadings should not be overlooked either. In addition to helping structure the post, they facilitate quick reading. Make sure your headings are not too generic and be as descriptive as you can so people know what they’re going to be reading next. For example, if you’re describing the 10 steps of your migration plan in a section of your article, naming it just “Steps” might not be the best idea. There is usually going to be a better subheading, like “A 10-step migration plan”.

## Timing is key

To choose the most appropriate angle for your topic, you should consider the stage of the technology you’re discussing. You can use [the Gartner hype cycle](https://en.wikipedia.org/wiki/Gartner_hype_cycle) to help with that (thanks, [Crafts Records](https://craftsrecords.org/), for the inspiration). Essentially, this model is a graphical presentation that displays the maturity, adoption, and social application of specific technologies.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1e905p1f7dhj1613xac9.jpg)

The most common categories of technical blog posts include:

A brief introduction to a new technology that you’ve just discovered.

- Things you wish you’d known one year ago or as a junior.
- Resolution of the pain points spotted around you.
- Feedback about the implementation of a technology.
- Postmortems.
- An explanation of your strongest convictions.
- Notes from conferences/meetings.

Among those blog posts, some will be more relevant at certain points in the evolution of technology. For instance, the introduction to a technology will be more appropriate between the Technology Trigger and Peak of Inflated Expectations phases, while feedback will be better suited to the period that follows, when the technology is often decried. The Plateau of Productivity phase is often the best time for expert posts on specific technology details.

## Include peer review into your proofreading process

Include reviewers in your blog post proofreading process, just as you would with your code. There is no need to involve too many people in the process — 2 or 3 is usually enough. To efficiently incorporate reviewers' feedback, establish a clear system for tracking and addressing comments. Use a collaborative document-editing platform where reviewers can leave comments directly in the document. 

In addition, tools like [Grammarly](https://www.grammarly.com/), [Hemingway](https://hemingwayapp.com/) or [Wordtune](https://www.wordtune.com/) can help with grammar and readability. These tools can catch errors missed by human reviewers, ensuring your content is error-free and easy to read. They can also provide valuable suggestions for improving your writing clarity and coherence.

Finally, take a break after writing and revisit your blog post with fresh eyes. Reading your text aloud can help you identify any awkward phrasing missed during the initial writing process.

## This is the conclusion you should never write

A conclusion usually summarizes what has been discussed in the post and talks about what is to come. When writing the final paragraphs, most people are tired and just want to finish their post. Let’s face it, conclusions are often sloppy.

Start by avoiding giving your conclusion the subheading “Conclusion”. Whenever possible, it is better to find something that has more meaning. And keep in mind that your conclusion will be the last thing your readers remember. So if there is a place where you can be creative about making an impression, this is it!