Table of contents
- Introduction 👋🏽
- What is technical writing?
- What you need to know
- And one (or) more thing(s)
Technical writing is for anyone interested in technology. If you probably want to get into technical writing, or are curious about it and want to figure out if it is for you, then you have come to the right place. Here is a simple guide to get you started.
What is technical writing?
Technical writing is a form of writing that provides information that the user can easily read. These pieces of information are technical documentation; they can be in the form of user guides, tutorials, and requirement documentation. You can read more about documentation in this article called Technical Documentation - By Blessing Ene Anyebe.
What you need to know
What I’ve learned in the past three years as a tech writer is that you will need to ask a lot of questions which could be a what, why and how. Whether you are a developer, a writer or neither, you need to unlearn everything you think you know about technical writing; why? Because assumptions without understanding can affect the foundation of your writing journey.
"Don't Make Assumptions. Find the courage to ask questions and to express what you really want. Communicate with others as clearly as you can to avoid misunderstandings, sadness and drama. With just this one agreement, you can completely transform your life." ~ Don Miguel Ruiz
I strongly suggest you also get a course, many underestimate how effective it is. You waste time and effort by learning through different sources that can negatively affect your learning process and consistency. Online Courses are specific and provide the necessary resources to make you a successful tech writer. Udemy has a lot of technical writing courses. You can visit this link to check them out - Udemy Technical Writing Courses.
For free courses to get you started, you can check out:
As you begin your journey as a tech writer, here are some things you also need to know.
Learn how to write
Having a writing skill is the first thing you need to have. It equips you with better ways to communicate to your readers and helps them understand what it is you want them to know. One reason you need this skill as a technical writer is that technical terms and concepts require clarity for different levels of readers. I’ve seen content that could bore readers and leave a wrong impression, and I have also been a victim of foggy writing.
Here are some things you need to understand:
Know who you are writing for
A technical writer should always put their readers first; to do that, you need to know who they are and provide the best way to communicate with them. Your audience may have different levels of understanding; this is where empathy comes in. You need to realise not everyone will understand what you write, but you can figure out how to communicate them better.
There are different strategies you can use when writing for experts and beginners. Here are some tips that can help you achieve your goal.
Writing for experts
- Find out the more background information for experts
- Only use terms you know experts are familiar with, do not assume
- Present concept and provide each part and process in detail
- Provide graphics to support ideas (Graphs, Tables, Diagrams)
- Think of questions experts might have.
Writing for beginners or non-experts
- Write an overview of the subject of the project
- Write documentation least knowledgable readers can understand
- Illustrate and explain terms and concepts
- Provide information in the order they need to follow
- Reduce the information to a step by step instructions on how to perform a task when necessary
- Use lots of whitespaces to make the subject look less complex
- Segment documentation into sections and descriptive headers.
Have a Style Guide
A style guide helps you write consistent content across all your documents. There are many style guides out there you can choose from, but you can write your style guide as well. I already wrote an article about this, so you can check out how to write style guides here on hashnode.
Develop your writing process
It is good practice to have a writing process, or you will waste a lot of time meeting your goals and even more time keeping up with your random form of writing. A technical writer needs to have a writing process. Here are five familiar writing processes you can follow:
When you have a plan, things become very convenient for you. If you are probably wondering what the stage of the process entails, here’s a list of what you can do to make a successful plan:
- Gather the necessary information you need and do your research
- Defining your audience
- Defining the goal of your documentation/content
- Figuring out the tools you need to get it done
- Setting up a timeline
Once you have sorted that out, you can go to the next stage, the content structure.
I believe you already know the saying:
“If you fail to plan, you are planning to fail.” ~ Benjamin Franklin.
Your content structure in this context is your outline, which refers to how you lay out your content. Structures guide your content and provide an excellent foundation to build your idea. Once you have it in place, you can quickly improve and update your content as it develops and becomes more comprehensive. There are various structure methods you can choose. See more about this from The Australian Manual or check out Structured Content by NATALYA MINKOVSKY.
A draft is where your writing comes in. It does not have to be perfect. You already have a structure that guides your content, so let your writing flow. Avoid any temptation to perfect every sentence you write; it can slow you down and can also hinder your collective thought from flowing freely.
In the review stage, you go through your content again to ensure your content is clear to read, accurate, and well-edited. For editing, Grammarly is an excellent tool for you.
You can also share your content with a colleague or a fellow writer to review and get feedback.
Finally, you are good to go and publish. You have done your research, outlined, drafted your content and reviewed it. Where you post may depend on your company's platform if you work under one. Keep in mind that publishing is not the end; it’s a cycle you must repeat if you want your content to stay updated.
Here are some websites you can visit if you want to publish an article.
Join a community/forum
This one, for me, is a no-brainer. Communities provide you with many opportunities to learn, grow, connect with other writers and stay up to date with what’s happening in the tech writing industry.
Here are some communities/Forums you can join:
- WriteTheDocs | Slack (Highly recommended)
- WriteforTech | Twitter
- Technical Writing Community | Linkedin
- Technical Writing is Easy | Medium
- I’d Rather Be Writing
And one (or) more thing(s)
Read a lot; if you do not read at all, you will likely not improve. Keep writing anytime you can, and trust the process.
Put some empathy into your writing. People read less and less lately due to so much information, so if they can quickly get what they need, that’s a big win for you. A technical writer is also a technical communicator, so care more about your audience than your writing. That doesn't mean you should not care about the way you write.
You can only understand people if you feel them in yourself. ~JOHN STEINBECK
If you are concerned about job opportunities, do not worry. According to the U.S BUREAU OF LABOUR STATISTICS:
“Employment of technical writers is projected to grow 12% from 2020 to 2030 faster than the average for all occupations. About 5,500 openings for technical writers are projected each year”.
That is just according to the united states alone. Many more job opportunities are opening up every year. You do not necessarily need a degree to get the job, but you need contents that can back up your qualification.
You can find Jobs on the following platforms:
Other useful references:
- How to Write a Style Guide - Segun Olumide Light
- Technical Writing For Beginners - Amarachi Emmanuela Azubuike
- Technical Documentation Simplified - - Blessing Ene Anyebele
- How to Write API Documentations - Josh Fechter
- Todos, Workflows and Best Practice in Technical Writing - Blessing Ene Anyebele
I wish you a great experience in your technical writing journey. Do feel free to share and like this content. I’d take that like a cup of coffee.