8 Valuable Technical Writing Lessons I Have Learnt So Far in 2023 (Beginners Perspective 🧐)

Introduction

Have you ever experienced problems while operating an electronic device and resorted to reading its user guide or manual? If the answer is yes, then you have benefited from technical writing. Technical writing breaks down technical jargon into easy-to-understand steps that a non-technical person can understand.

This past week, I attended a Twitter space hosted by Wisdom Nwokocha, a professional technical writer, and took home with me a few lessons, most of which comprise the content of this article.

What is Technical Writing

Technical writing is a tool to communicate complex topics by dividing them into clear steps for the user. It guides product end-users to carry out specific tasks.

With that in mind, we will delve into the eight lessons I have learned.

Lesson 1: Do You Need a Programming Background

Contrary to mass perception, you may or may not require a programming background. That is because technical writing transcends the technology space, precisely, programming.

Technical writing is present within multiple professional fields, such as legal, engineering, banking, finance, aviation, electronics, healthcare, and education. For instance, a medical practitioner writes medical manuals and other healthcare-related documents, and a lawyer writes legal analyses and legal rights to express legal duties. The same applies to engineers, accountants, and more.

First, develop a deep understanding of programming concepts if you write about programming.

Lesson 2: Is Technical Writing Easier Than Programming

Generally, writing involves breaking down concepts for the reader. It would be best to understand the respective topics to do that effectively. In the context of this article, our primary focus is on programming.

So, is technical writing easier than programming? NO, writing requires a lot of research, skill, and problem-solving - similar to being a programmer. Technical writing is a different ball game and is just as 'difficult' as being a developer, Software Engineer, programmer, et al. Note: Difficult is relative 😉.

Despite all that, good research is underrated; therefore, to be a successful technical writer, you must use research to improve.

Lesson 3: Applying For Technical Writing Jobs

As discussed previously, before applying for a technical writing role, you must be familiar with the subject matter. As a beginner, how do you go about applying for these roles?

I will split this into two main points;

1. Beginners Process — As a beginner, before applying for technical writing roles, it is advisable to document your journey. Documenting your journey will polish your writing skills and help you better understand what you are learning. While building side projects and learning new concepts, write about them.
2. Resume — Your resume is your selling point to potential clients. Many ask whether you need to tweak it while applying for a technical writing role. The short answer is NO. Suppose you are a software engineer, and your resume highlights your skills; hence even as a technical writing beginner, your qualifications will suffice.

Lesson 4: Types of Technical Writing

Some types of technical writing are;

• Assembly Manuals — assembly manuals provide instructions on how to operate the equipment. Writing assembly and repair manuals requires technical skills to understand a machine or equipment's assembly and re-assembly process.

• Technical Documents, Reviews, and Reports — the aforementioned are a mix of academic reporting and technical research-based guides. Reports explain the process and outcome of any research. Technical reports come in several shapes: preliminary research reports, case studies, business plans, feasibility reports, proposals, etc.

• User Manuals and Assistance Guides — If you need answers to specific usage-related questions for consumer products, user manuals and assistance guides are made for you. User help guides break down a product into individual parts and clarify the functionality of each component. It also answers questions about each part's solutions and provides queries you may have throughout a product's lifespan.

• Medical and Scientific Papers — Researchers use these academic papers to interpret their findings, organize and condense them into engaging content, and publish them in various journals, newsletters, and online platforms.

• Content Marketing — organizations must build a "buzz" for their products to target customers. With content marketing, they target end-users of products to inform them of new products, which in turn, brings traffic to their site. The end goal is for some readers to become potential customers eventually.

Lesson 5: Information Architecture

Information Architecture focuses on organizing, structuring, and labeling content effectively. Information structure is critical in technical writing as it helps end-users comprehend and use the relayed information efficiently.

When you apply it correctly, you will create high-quality content. Group the content into categories based on user's needs and how users understand the information. My three main takeaways from Information Architecture are;

• Structure — formatting and labeling encompass format. Knowing what type of lists to use, where to use tables, titles, subtitles, etc., is essential. A well-formatted technical article gets the point across to the reader fast and makes the content easy to digest.

• Style Guide — a style guide consists of principles and standards for writing and designing content. It defines the style that one should use throughout the technical document. The purpose of a style guide is to write clear documentation and maintain consistency in tone and style. Some popular style guides are Google Style Guide, SAP Style Guide, The Handbook of Technical Writing, Apple Style Guide, Oxford Manual of Style, and more.

• Markdown — According to Markdown Guide, Markdown is a lightweight markup language that you can use to add formatting elements to plain text documents. Created by John Gruber in 2004, Markdown is now one of the world's most popular markup languages. Blogging sites such as Medium, dev.to, and hashnode use markdown to add formatting; hence to properly format articles, you need to understand Markdown.

Lesson 6: Plagiarism

In technical writing, research is necessary to piece information acquired from various sources. While using data from external sources, paraphrase the content or, better yet, quote the reference.

Lesson 7: Challenges of Technical Writing

Technical writing comes with its fair share of challenges. Here are a few;

• Disorganized structure — as discussed, the design of your content is essential. Poorly structured technical documents will confuse the readers. Information should be easy to find, and sections should flow with each other. During the planning stage of documentation, don't skip, so you have a system to follow when writing the content.

• Insufficient information about the users — Successful documentation relies on a deep knowledge of users, without which your technical writing is useless. Before you begin writing technical documents, you need a precise idea of who your users are so you can write compelling content. To understand the customer, conduct user interviews and collaborate with the marketing team to share their knowledge about customers.

NB: Technical writers are user advocates in the organization and provide them with a voice within the product.

• Getting people to review your work — Unreviewed documentation will be flawed to the detriment of the end user. Defective documentation taints reflection on your writing and the organization for which you are writing. While asking for reviews, be concise about the feedback you want. Also, ask for reviews enough time in advance to get the most honest reviews.

• Present Your Documentation In User-Friendly Format — Say you guide users to customize a software product. If the readers have not installed the software yet, how will they customize it? So hyperlink the software installation link where necessary. While writing technical documents, hyperlink critical phrases that you must elaborate to your readers.

• Consistency — Technical writing should be coherent for users and convey clarity. Documents written over time, edited by various authors, or updated in a haphazard way are inconsistent. Inconsistency exists in many forms, i.e., style, layout, tone, etc.

Lesson 8: Payment Methods

Payment platforms used by most big companies include PayPal, Payoneer, Stripe, and more. Well-established companies use their payment policies, while startups are more flexible and can accommodate writers' options i.e, MPesa, Flutterwave, Simplepay, etc.

Conclusion

At the end of the day, as a beginner, it's all about the quality of the content and not quantity. Also, as a technical writer, you should learn how to create docs such as API Docs. Note: API Docs pay more than blog articles 😉.

See you at the next one.

Peace ☮️✌️