Get Better At Technical Writing 2: Don't Start With Writing

Introduction

Technical Writing is not just about writing. There are a whole lot to consider and do before writing even the first draft.

A technical writer is, first of all, a researcher and tester. A huge amount of the writing process should involve research/learning, testing the product or a language's use case, before any writing should be done.

A famous scientist once said, "If I have 1 hour to cut down a tree, I will spend the first 55 minutes sharpening my axe." Accordingly, it is healthy to say that 80% of the writing process should be spent not writing, but researching and testing.

Typical Writing Processes

If you work with a team of developers, your job may be limited to creating manuals or tutorials on softwares they developed, writing documentation of APIs or services they built, etc. In your case, a typical writing process may involve:

• Installing the software and it's dependencies on a platform. You may have to write step-by-step installation and setup guide as you do this. You may also have to test this guide on another platform, while writing the procedures. Not all your readers will be using Windows, or AWS, etc. The rule of thumb here is to carry out tests on as much widely used alternative as your product or company allows.

• Testing the software as much as possible, trying to understand how it works in every aspect. This is to reduce the amount of complaints that go to customer support, either by explaining obscure concepts in the official manual, or writing more FAQ articles.

• Reporting bugs you found while testing. You don't have to solve them yourself, no. You're not a bug hunter.

• Writing the content completely, then redrafting if need be. Check for grammar errors, punctuations misuses, and consistency.

Read Now: Get Better At Technical Writing: The Beauty of Consistency.

• Updating your write-ups as time goes on and technologies advance. In a future article, I will explain how to automate this process.

If you do not work with a team, you are most likely a developer/engineer who found the beauty of Community as a Service (CaaS). You learn something new and want to teach it to the community through writing. If this screams you, then your writing process involves most of these steps, but a lot more coding.

The following tips will explain how to improve your pre-writing phase.

Define Your Audience:

This is an important first step in pushing out a content. Who are you writing for? What is the bare minimum knowledge they need to have to completely understand your write-up?

The foremost duty every technical writer has is to create content that their intended audiences will read and find useful. Any other duty is inferior to this.

If your audience are experts, you have to tailor your write-up to suit experts, not beginners. This means you don't have to explain what every term mean, or put the reader through the process of installation and setup of a software.

Do Your Own Research

A common thing I noticed among the expert technical writers I know is that they create honest work. Producing unique, honest, and unplagiarized content means you know enough to write in your own words. You know enough to create your own use case.

From experience, some companies would expect you to create and promote contents around their products, as a means of influencing their sales of those products. More often than not, you would have to learn how a particular product works, and technologies you would need to interact with the product to create your own use case.

Research sparks up more curiosity in the technical writer. Some newbies in technical writing often ask questions like: how to find new topics to write about, how to write unique content for a topic already written on before. A great way to do either of these is to embrace research.

Staying updated or learning new things about a tool or technology would definitely leave you asking, "What if I could use this tool to do X?" at some point.

Test Before Publishing

Writing an article or manual for a product, a software, or a programming language means you are familiar with it through and through. You know your way around it enough to teach someone else how to use it. In this sense, testing does not mean improving performance, but increasing personal knowledge.

This is mostly the case for writers who work in teams. If this is you, then you have the option of informing developers about the bugs and issues you find while testing.
In another sense, testing means making sure your content is unfalsifiable. Put testing at the back of your mind and you're sure to produce great content that your readers can find useful.

This is the case for CaaS writers. Before clicking the Publish button, make sure you have tested every piece of code you included in your write-up, in as much widely used platforms as possible for you.

In software development, there is the concept of test-driven development (TDD). TDD entails not taking a software into production stage until it is thoroughly tested.
For you, the technical writer, your software are docs and articles, and you have to test thoroughly before taking them to production.

Finalize your writing process by testing everything you have written.

Benefits of Researching and Testing

• You push out content that is absolutely useful to your reader - your ultimate goal for writing in the first place.
• It is not just useful, it is also easy to implement/reproduce by your readers. In other words, it works on other people's machine too.

• It prevents hundreds of complaints/enquiry emails to customer support. Pro tip: if you work with a team as a technical writer, find out what customers are saying about the software. Ask yourself if there's a way to better the situation by writing more.This might lead to an increase in your paycheck.
• Drawing appreciation from readers, it inspires love for the software or language. For example, when generics came to Golang in November 2021, it didn't take long before a developer wrote an article on using generics in a Golang project. That discovery made me love the Golang Community, and developers' energy even more.
• During research, you will find potential topics to write next about, especially if your research entails learning new concepts or technologies.

I hope you refer to these tips before you start writing your next awesome article! Also, check in next Thursday for another article in the series.