In 2021, I joined technical writing, where I have written close to 20 paid technical articles and made more than $6K online.
From my experience, writing a good technical article is not a walk in the park. A good technical article is an article that breaks down complex concepts into simple and easy-to-understand language.
As a technical writer, to break down complex concepts into a simple and easy-to-understand language, you need to:
- First, understand the topic you are writing about.
- Second, know the audience you are writing for.
- Third, know how to structure an article to deliver your message to your reader.
- Finally, Know how to use the right voice and tone in your writing.
To do all the above, you need a good technical writing process.
In this article, you will learn about the technical writing process I use to write better technical articles for my clients.
Here are the steps in the technical writing process that I will be covering:
- Step 1: Research.
- Step 2: Prepare to write.
- Step 3: Write the first draft.
- Step 4: Review.
- Step 5: Editing.
- Step 6: Approval and publishing.
Step 1: Research
Firstly, do a google search of the topic you are writing about and review articles related to the topic. As you review the articles, take notes to get a better understanding of the topic.
Also, you can ask ChatGPT about the topic. Then compare the information you get from ChatGPT to the information you got from Google search.
For example, I started working on a new topic for a client technical article this week. Here are the notes I took while researching the topic.
Note: You need to compare information from ChatGPT with information from Google search because ChatGPT can sometimes provide inaccurate information.
Secondly, determine the format and structure of the topic you will be writing about.
Types Of Article Structures
There are two types of technical articles in technical blog writing.
- Procedural Articles: These articles walk the reader through accomplishing a task step-by-step.
- Conceptual Articles: These articles help readers understand the topic deeply and build a foundation for further learning.
Below are different different structures of the articles.
Thirdly, identify the target audience of the topic you will be writing about.
The simplest way to identify your target audience is by determining what your audience needs to learn.
Write down a list of everything your target audience needs to learn in the technical article you will be writing.
Step 2: Prepare To Write
Firstly, determine the objective or aim for the article you will be writing.
Identifying your audience in step one will help you determine the article's objective.
The article's objective can be to help the reader learn something or solve a problem.
Here is an example of an article objective.
Secondly, create an article outline.
An outline, in simple terms, is a skeleton of a finished piece of writing that maps the topics you will cover in an article.
An outline provides a structure that ensures your ideas flow logically and clearly.
Determining article format and structure in step one will help you create an article outline.
For example, here is an outline of an article I wrote for the DbVisualizer blog.
Note: After determining the article's objective and creating an outline, if it is client's work, you can send the article to the client to get feedback to ensure you are on the same page.
Step 3: Write The First Draft
Firstly, include the goal of the article in the title. Below is how a label can be formatted,
Title Format
How To With < Software or Technology>
Example
How To Create A Calculator With JavaScript
Secondly, start writing the article introduction. The introduction of every article should have 1 to 3 paragraphs.
Questions a good intro should answer
- What is the problem being addressed?
- What is the solution to this problem?
- What will the reader learn?
Thirdly, write the prerequisites. The purpose of prerequisites is to spell out exactly what the reader should have or do before they follow the current tutorial.
The format is a list that the reader can use as a checklist. Each point must link to an existing tutorial that covers the necessary content or the official software documentation.
This allows you to rely on existing content known to work instead of starting from scratch.
Fourthly, start writing the article body in steps. The steps are the parts of your article where you describe what the reader needs to do and why.
A step contains commands, code listings, and files explaining what to do and why you're doing it this way.
Lastly, write the article's conclusion. The article's conclusion should summarize what the reader has learned or accomplished by following your tutorial.
Step 4: First Draft Review
After writing the first draft, send it to the client, subject matter expert, or someone with good knowledge of the topic you are writing about for review.
Having the draft reviewed by the client or subject matter expert ensures that the article is technically accurate and meets the article's objective.
Step 5: Edit And Revise
Editing and revising is where you shape the reviewed draft into a final draft. Make sure that you take a break between writing and editing. Taking a break will enable you to view your work with fresh eyes.
You can use tools like Grammarly in the editing process to check spelling, grammar, style, and punctuation mistakes.
Step 6: Proofreading And Approval Of Final Draft
Proofreading your final draft is when you have finished your writing but are not ready to publish it or hand it to your client for approval.
Here you go through your article to catch:
- Any spelling mistakes
- Grammar errors
- Typos
- Formatting errors
- Incorrect structure or syntax
After proofreading the final draft, send it to the client for last review and approval.
Step 7: Publish The Finished Article
The client will publish the article if no more changes to be made to the final draft. If it is a personal article, you can post it on your blog or free blogging platforms for developers like:
- Medium
- Dev To
- Hashnode
Conclusion
You have learned how to write a good technical article step-by-step in this article. If you liked the article, follow me on Twitter for daily tips on technical writing.
Top comments (24)
Awesome! Thanks for sharing this information. These are great points to focus on when writing, especially in a developer community like Dev.to. Clarity, conciseness, and relevance are key to delivering valuable and impactful messages. By sharing your knowledge and experiences, you can help others grow and succeed, and establish yourself as a leader in the tech community. Thanks again for the insight!
You are welcome.
Looking forward to creating even better content.
Great content you have here Boonie!
As a developer, I never thought I would become a writer, but I have always enjoyed teaching, mentoring, and sharing content with others in various formats. It wasn't until recently that a client approached me after seeing my writing on Dev.io or my website and asked me to write for them in a similar style. To be honest, I was initially surprised but then realized that I had been doing this for years, nothing new here, just never publishing it. It's simply a new format with different processes.
I have read some of your work, and I must say that it is excellent. I really like your style and the value you provide.
If it is possible, I would appreciate your insights on how you structure and base your compensation, as well as any advice you have on negotiations.
Note: I have tried to download your content from Gumroad but it doesn't work. Not sure why!
This is awesome.
Send me a Twitter DM.
twitter.com/The_GreatBonnie
At the moment I follow 50-60% of these steps... I will try with the next one to follow as much as I can.
That's awesome.
All the best in your next article.
Hope it turns out well.
Great post
Thanks.
Insightful.
Thanks for sharing
Thanks for sharing Bonnie
You are welcome, Abdulsalaam.
Good stuff, and I wish we wrote (and talked!) a lot more about this topic.
One useful tip I would offer is, 1) set a limit; 2) deliberately overshoot; and 3) budget at least 50% for editing the overshoot into the limit. Let's say you 1) set a goal of writing a six-pager (or 3000 words). Then you should 2) deliberately try and write (let's say overshooting by half) nine pages (or 4500 words). Lastly, 3) spend half your overall time limit editing from 4500 to 3000 words.
Open-ended writing is a curse, and editing/distilling is where the real magic lies anyway. One excellent resource I can recommend: youtube.com/watch?v=vtIzMaLkCaM
Wise words. Although that last drop from 4500 to 3000 is tough!
Aside, say writing for Kodeco you are aiming for max 4k, but can overshoot if absolutely needed.
Readers patience / attention will wander the longer you go on though.
Basically, don’t be a recipe article (aka tons of flowery exposition … sure put your personality in but readers don’t care if Your cat looks like a ball); try and hit your point in as few words as possible but with context.
(He says being flowery)
I have just started writing a technical blog, and from my next post on will try to follow the steps you describe
That's awesome.
Looking forward to see what you come up with.
I started writing articles on my blog and some other platforms, I will try to follow these steps from now on.
Good to hear that, Syed.
All the best in your writing process.
Thank you! In recently time I started to get interested about a write tech articles. I always read, I always follow tutorial, I always check on StackOverflow and now I think that It is correct to share some of my knowledge! So Thank you! 😁