The benefits of being a technical writer

10 Mar, 2020

From time to time I occasionally write technical articles on a variety of subjects. Most of my full-time work is modeling, designing and documenting solutions which involves a lot of workshops and a lot of writing. It would seem strange that I would want to go home and write some more, especially considering that for the last few weeks I have had a number of ghost-writing jobs where my name is not even attached to the piece. I thought it would be interesting to have a look at my process for writing technical articles, why I write them and why I think most technical people would benefit from writing technical articles.

Why I write

Before getting into my general process for writing articles, the big question I guess is - Why do I bother? Plenty of people write articles, lots of them are probably more knowledgeable than me. I’m sure XYZ has been written about before. There are a quite a few reasons I can probably give to that answer, but the most important ones to me are:

My job takes me “off the tools” - I don’t build and deploy stuff anymore, I plan and design. Technical articles give me a reason to play with new technology.
I also love learning new technology and discovering new things to build with.
It actually helps me to continue improving my ability to explain technical concepts to non-technical people by assuming the reader knows nothing about the technology or concept.

How to write technical articles

I have a fairly particularly method when I am writing technical articles that may be a little more involved than other people, but I find it works for me. For most articles I find the standard introduction, method, conclusion about a single subject works the best. Using this structure, I have a fairly simple, five step process to writing an article. I also find having a structure, any structure, makes the task a little less daunting.

Step 1 - Problem statement

My first step, and sometimes the hardest, I have is coming up with a problem statement that I am going to solve as an example of implementing the technology or principle. While the general purpose of a technical article is to detail or demonstrate how to use a technology or apply a principle, you also need to be somewhat entertaining. I find having a problem statement allows you to both tell a story and provide context to help with understanding.

Step 2 - Research and Outline

The next step is to do some initial research to develop a rough outline based on the previous problem statement. Most of this research and design comes about the actual steps I think I need to complete the task. This step give me a rough idea around how many words I need per step to ensure I don’t go over or under any word limits too much. It also helps keep me on track for how much more I need to write.

Step 3 - Screenshot and notes

This is the most time consuming step of the process - running through from start to finish solving the problem proposed in step 1. While I use my outline to go through these steps, I am also taking screenshots of the process and expanding the outline with fairly simple notes on the steps I have taken. I always try and ensure that I capture every step, but I work on articles in my spare time so sometimes parts a missed. This is where screenshots help keep the process in my mind.

Step 4 - Final draft

With my notes and corresponding screenshots in hand, the time has come to draft the final stage of the article. In this stage I go through from top to bottom and:

setup the article in the introduction
expand the notes to ensure the story or problem comes through the process
select and edit screenshots (or provide appropriate images) to illustrate the process
summarise and put together next steps at the end

Throughout this stage I try and keep the word count as succinct as possible but I am not overly worried about word count or length, I find it’s more important to get a clean, consistent piece out first.

Step 5 - Follow, edit and finalise

The last step is to clear the environment I setup to write the piece and follow my own instructions, preferably a day or two after the final draft. This is to help ensure I don’t miss any step or gloss over something important. You will sometimes miss some small step that can be critical for readers to mirror your journey, but this step helps reduce this as much as possible. It also gives you a chance to flesh out or trim down your article to bring it back in line with the word limit.

Why should you write

When I started writing as a bit of a side project it was purely to help me keep motivated and to help build out this website. I really wanted a place I could document the things I do and help others with things I learn. But I have found there are some other big benefits that all technical people could benefit from, including:

Putting yourself out there - This was a big one for me. Putting yourself out there and writing something that has your name on it can be pretty intimidating. What if I say something wrong, what if I am not an expert, what if people don’t like it. So what if this happens? If something is wrong, edit or write a follow up. If you are not an expert, learn and share with other beginners. If people don’t like it, they won’t read or they will say something nasty: ignore both and write for yourself. If you track the statistics on your writing, it feels pretty good when X number of people this week read your stuff.
Learning something new - Learning new things is always important, especially in the current environment. Being able to learn new things, explain them and put them into practice is such a useful and valuable skill. Being able to show people you can work with XYZ even if you don’t use it in your current job helps a lot with transitional step, if you want to.
Improve your written communication - Not many developers like writing documentation and consequently not many of those are good at it. Getting comfortable writing documentation and conveying ideas can really help improve your work and, more importantly, help you become well rounded. It also helps you design better by thinking through the why you made specific choices.
Meet new people - I have met a number of really cool people who have read my work and reached out. As someone who struggles with social networking and social situations in general, this is really powerful. People are coming to me to talk about stuff, which means there is zero effort required for me to reach out.

These days there is no limit to free services that can host your writing, you don’t need to go in. And in the long run, it is well worth the effort.