Introduction
Technical Writing is not just about writing. There is a lot to consider before writing even the first draft that will help you improve your technical writing.
A technical writer is, first and foremost, a researcher and tester. Before any writing is done, a large part of the process should involve research/learning and testing the product or a language’s use case.
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.
This article is part of our Getting Better at Technical Writing Series. You can read the previous series before you jump to this one.
- The Beauty of Consistency: We provide valuable tips on achieving consistency, drawing from a wealth of experience in commercial technical writing.
- [You’re here] Don’t Start With Writing: Technical Writing is not just about writing. There is a lot to consider before writing even the first draft.
The Typical Writing Process
If you work with a team of developers, your job may be limited to creating manuals or tutorials on the software they developed, writing documentation of APIs or services they built, etc. In your case, a typical writing process may involve:
- Installing the software and its dependencies on a platform. You may have to write a step-by-step installation and setup guide as you do this. You may also have to test this guide while writing the procedures on another platform. Not all your readers will be using Windows, AWS, etc. The rule of thumb here is to test as many widely used alternatives as your product or company allows.
- Testing the software as much as possible. Trying to understand how it works in every aspect. This will reduce the number 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.
- Write the content completely, then redraft it if necessary. Check for grammar errors, punctuation 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 this article series, 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, your writing process involves everything a team worker does 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 content. Who are you writing for? What is the bare minimum knowledge they need to completely understand your write-up?
Every technical writer’s foremost duty is to create content that their intended audiences will read and find useful. Any other duty is inferior to this.
If your audiences are experts, you must tailor your write-up to suit them, not beginners. This means you don’t have to explain every term or walk the reader through the process of installing and setting up software.
Research
A common trait among expert technical writers is that they create honest work. Producing unique, honest, and non-plagiarized content means you know enough to write in your own words and create your own use case.
From experience, some companies would expect you to create and promote content 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 the 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 and how to write unique content for a topic already written before. A great way to do either of these is to embrace research.
Staying updated or learning new things about a tool or technology will eventually lead you to ask, “What if I could use this tool to do X?”
Test
Writing an article or manual for a product, software, or 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 of the product or software.
This is mostly the case for writers who work in teams. If this is you, you can inform developers about the bugs and issues you find while testing.
In another sense, testing means making sure your content is unfalsifiable. Keep testing in mind; you’ll produce great content that your readers will find useful.
This is the case for CaaS/Freelance writers. Before clicking the Publish button, ensure you have tested every piece of code you included in your write-up on as many widely used platforms as possible.
Software development uses the concept of test-driven development (TDD), which entails not releasing software into the production stage until it is thoroughly tested.
For you, the technical writer, your software is docs and articles, which you must test thoroughly before putting them into production.
Finalize your technical 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 in writing.
- It is not just useful; it is also easy for your readers to implement/reproduce. In other words, it works exactly as you said it would on your reader’s end.
- It prevents hundreds of complaints/inquiry emails from being sent 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 inspires a love for the software or language.
Conclusion
To sum up, Technical Writing is much more than putting words onto a page. It’s a craft that demands careful research and thorough testing before ink hits the paper or fingers touch the keyboard.
A technical writer, essentially, wears two hats: that of an investigator and an experimenter. These initial steps pave the way for a successful writing process.
Imagine this: before chopping down a tree, spend most of your time sharpening the axe. In the context of writing, this means dedicating a whopping 80% of your effort to researching and testing and only 20% to actual writing. It might sound counterintuitive, but it’s a proven way to ensure top-notch content.
The key principles remain constant whether you’re part of a development team or a lone wolf in Freelance Writer or Community as a Service (CaaS). This includes crafting installation guides, conducting rigorous software tests, reporting bugs, fine-tuning your content, and keeping everything up to date.
Remember that your audience comes first—always. Tailoring your content to their needs and background knowledge is paramount. Robust research leads to fresh, honest, and unique content. Testing isn’t just about checking for accuracy; it’s also a way to truly understand your writing’s ins and outs.
So, why go through all this trouble? The rewards are worth it. Content born from diligent research and exhaustive testing isn’t just useful—it’s practical and easy for your readers to follow. It cuts down on customer questions, earns you a nod of appreciation, and fosters a genuine connection between your readers and the subject matter.
In the grand scheme, Technical Writing isn’t just about words—it’s about problem-solving, clarity, and sharing insights. By embracing the power of research and testing, a technical writer becomes a reliable source of guidance, translating complex ideas into accessible knowledge for eager readers.
Contentre helps technical writers stay organized and gain more clients. Grow your technical writing career in one place.
Now that you’re here, let me briefly recap the most important features Contentre can offer you:
- Organize your content in categories, topics, and tags
- Create and manage multiple clients
- Create and manage multiple personalized portfolios
- Get statistical analytics of your content revenue, top categories, and tags.