A Guide To Technical Writing: Dos & Don’ts

6 min readApr 9, 2021

#NoCode Series: Do you want to be a techie without writing code? Here’s one way to.

Before I ventured into Technical Writing, I was already involved in other forms of writing — copy, content, and academic. However, for some reasons, I was a bit sceptical about being a technical writer. Honestly, I think it began with the name. “Technical Writing” sounded sophisticated, and I felt like I was not good enough for it.

Months down the line, I partook in a technical writing challenge, after which I went into technical writing proper. I now work as a documentation writer. Some things have helped me on this journey; I have outlined them to share with you.

First off, what is technical writing?

The Society of Technical Communication broadly defines technical writing as “any form of communication that shows one or more of the following qualities:

Communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations.
Communicating by using technology, such as web pages, help files, or social media sites.
Providing instructions about how to do something, regardless of how technical the task is or even if the technology is used to create or distribute that communication.”

The first time I read the definition above, I skimmed through it too. So here’s the simple meaning of Technical Writing:

Technical writing is the art of documenting complex processes clearly and concisely.

Technical writing encompasses all documentation of complex technical processes. Have you ever unboxed a new home appliance and found a manual containing instructions on assembling or using it? That’s an example of a technical writeup.

If you have installed software in the past, you may have read a help file that guides you on the installation process. That’s another example of technical writing.

Why should you start technical writing?

Learn: To explain a concept or process to people, you must have an understanding of it. Therefore, to write more, you have to learn more. As a technical writer, you never stop learning. You have the opportunity to understand diverse concepts in different fields.
Help: Technical writing aims to help people who are new to something or stuck and need a solution. Being a technical writer enables you to proffer solutions and contribute to others’ growth while you grow too.
Earn: The tech industry is lucrative, and writers are not left out. As long as you can accurately document a process detailedly and effectively pass a message across, you can apply to be a paid writer/documentation expert.

As a technical writer, you learn, help, and earn simultaneously.

So as a technical writer, you learn, help, and earn simultaneously. Sounds good, yea? Here are a few dos and don’ts to note when writing:

Dos

Understand your audience:

How you write for beginners in a field differs from how you write for people in the intermediate level in terms of explanation, so you must factor that into your writing and tailor it to suit your audience. Before you write a piece, you must answer the following questions:

Whom are you writing for?
What skillset does your audience possess?
What level is the writeup targeted at? Beginners or Intermediates?
What problem do you intend to solve with this write-up?
What’s their average attention span?

2. Choose a style:

One common mistake writers make is copying someone’s (maybe a ‘renowned’ writer) writing style. While it is essential to have mentors and learn from people, it is equally necessary that you do not lose your voice in someone else’s. Be unique, stand out and write like you.

3. Have a checklist/process outline:

Here’s how I write:

I think of something I want to write on and pen down the idea, even if it pops in my head during my day-to-day activities.
I research — talk to experts, google, and I carry out the process I want to write about if I can.
I write my first draft and leave it.
After some time — hours or days sometimes — I return to read it out.
I self-edit and do final proofreading. I have a critic-friend to whom I send the final draft for an opinion and suggestions.
I proceed to publish and share.

All of these are what make up my checklist. You are less likely to skip a process or forget something when you have a checklist you follow. It helps you to stay accountable to yourself.

Get Olamide 'Pearl' Makinde’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

4. Write clearly and concisely:

Go straight to the point: Steer clear of unnecessary or confusing words. Don’t say in a paragraph what you can say in five words.
Format properly: Use lists, heading tags, bold, and italics for a better explanation, for readability sake, and to keep your reader interested and not bore them.
Write sequentially: When writing about a process, don’t joggle up steps. Write them out in a consecutive manner to not confuse the readers.
Include Images: Pictures, they say, speak a thousand words. In appliance instructional manuals, you’ll see that there is usually an image for every step. It helps to assure the reader that they are on the right track and also clarify things if they did not understand when they read it. A picture always reinforces the concept: normalize including images to buttress your point.
Define acronyms on first use.
Avoid excessive abbreviations.
Break your ideas into paragraphs.
Make it relatable: Do you remember when I asked for the skill level of your readers earlier? If you are writing for beginners, you should highlight likely problems they’ll face or things they’ll overlook so they know they are not alone or dumb. Make it relatable.
Use a grammar checker: Ensure that your writing is error-free grammatically. Wrong punctuation can mislead a reader; bad grammar can make a reader lose interest.

5. Use Developer-Tailored Blogging Platforms:

This is specifically for those who write for developers. Aside from being writing platforms, dev-tailored blogs are communities too. Developers would choose dev-tailored blogs to find answers to their problems before regular blogs, so you have a higher chance of reaching the audience you are targeting when you use such platforms.

6. Get an Editor.

7. Be consistent (Practise and make conscious efforts to get better):

Take a technical writing course.
Read.
Attend events.
Talk to people.
Partake in writing challenges.
Seek feedback, filter and implement relevant ones.

Don’ts

Plagiarize:

Plagiarism is both legally and morally wrong. It is unethical, unprofessional, and distasteful to steal someone’s ideas and present them as yours. I advise that you use a plagiarism checker like Prepost SEO or Duplichecker.

2. Assume:

Ensure that you have a solid understanding of the topic you are writing about. If it’s a documented process (e.g. an instruction manual or a how-to-XYZ article), it is vital to try it out or, at least, witness the process. If you have access to techies in that field, you could also consult them. If you are stating facts or citing statistics, make sure that they are from a reliable source and confirmed. Do not make up ‘facts’. The internet houses truckloads of relevant information; make good use of it. People are banking on you; you can’t afford to lead them astray.

3. Be in haste:

Although, as earlier stated, you should endeavour to be consistent with your publishing. However, in a bid to meet the deadline you’ve set for yourself, you should not rush. Go over your work, take time to gather information, and do not publish unedited pieces. Switch roles: put yourself in the shoes of your readers and read your draft. If you were without any knowledge of that topic, does reading it help you in any way? If possible, you can even get a friend to read through it and critic it constructively.

4. Put pressure on yourself:

You may find yourself comparing yourself and your writing to others; it is crucial to take it easy on yourself. As long as you make intentional efforts to get better, you will. Do not put unhealthy pressure on yourself.