DEV Community

Cover image for Technical Writing Process: How To Write A Good Technical Article
Bonnie
Bonnie

Posted on • Updated on

Technical Writing Process: How To Write A Good Technical Article

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.

Image description

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.

Image description

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.

Image description

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.

Image description

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.

https://twitter.com/The_GreatBonnie

Top comments (25)

Collapse
 
indika_wimalasuriya profile image
Indika_Wimalasuriya

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!

Collapse
 
the_greatbonnie profile image
Bonnie

You are welcome.

Looking forward to creating even better content.

Collapse
 
ahmednadar profile image
Ahmed Nadar • Edited

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!

Collapse
 
the_greatbonnie profile image
Bonnie

This is awesome.

Send me a Twitter DM.

twitter.com/The_GreatBonnie

Collapse
 
kasuken profile image
Emanuele Bartolesi

At the moment I follow 50-60% of these steps... I will try with the next one to follow as much as I can.

Collapse
 
the_greatbonnie profile image
Bonnie

That's awesome.

All the best in your next article.

Hope it turns out well.

Collapse
 
codeofrelevancy profile image
Code of Relevancy

Great post

Collapse
 
the_greatbonnie profile image
Bonnie

Thanks.

Collapse
 
lahitan profile image
Lahitan

Insightful.
Thanks for sharing

Collapse
 
clericcoder profile image
Abdulsalaam Noibi

Thanks for sharing Bonnie

Collapse
 
the_greatbonnie profile image
Bonnie

You are welcome, Abdulsalaam.

Collapse
 
tythos profile image
Brian Kirkpatrick

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

Collapse
 
tarasis profile image
Robert McGovern

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)

Collapse
 
alcb1310 profile image
Andres Court

I have just started writing a technical blog, and from my next post on will try to follow the steps you describe

Collapse
 
the_greatbonnie profile image
Bonnie

That's awesome.

Looking forward to see what you come up with.

Collapse
 
syedmuzamilm_43 profile image
Syed Muzamil

I started writing articles on my blog and some other platforms, I will try to follow these steps from now on.

Collapse
 
the_greatbonnie profile image
Bonnie

Good to hear that, Syed.

All the best in your writing process.

Collapse
 
ffex profile image
ffex

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! 😁

Collapse
 
geekdaniels profile image
Olufemi Oladotun Daniel

Thanks for this information, really helps. How do we deal with article lengths?

Collapse
 
jboxman profile image
Jason Boxman

Also recommend this post: diataxis.fr "A systematic framework for technical documentation authoring."

Collapse
 
eliaspereyra profile image
Elías Pereyra

This is really good, I'll use this format because it's really well structured and clear.

Collapse
 
shenghongzhong profile image
Shenghongzhong

Great! Where do you find those Gigi’s?

Collapse
 
annetawamono profile image
Anneta Wamono

This was a very helpful breakdown. Thank you!