Introduction

Technical writing is an essential part of any innovation. Innovatives such as scientists and engineers make use of technical writing principles to report a research finding, document manuals, product/software user guides, and explain procedures.

A technical content might be a manual, a pamphlet, a document, a report book/paper, or an article. Whichever form it may take, a technical content must be written to provide optimal usefulness for the reader. The writer’s skill, elegant writing style and beautiful use of words are useless if the reader does not achieve their ultimate goal.

The next section exposes a technical writer’s mindset as opposed to a random writer.

A Technical Writer’s Mindset

It should be well understood that everyone innovating something new must be able to write technical content. However, their level of expertise is not required to be as high as a technical writer. To put it more casually, an innovator may write an article and go away with it, but this is not the same for a technical writer.

The technical writer must write clear, concise, and detailed content while also keeping “searchability,” “scannability,” and “usefulness” in mind. This practice is a differential factor between a Technical Writer and a random writer.

Working for a company requires the technical writer to be conscious of their write-ups. Great technical documentation makes new employees productive in days instead of weeks, it prevents thousands of mails for customer support, is the difference between crippling downtime and rock solid stability, and serves as reference for others.

The next section introduces best practices in the art of technical writing.

Best Practices in Technical Writing

1. Understand Your Audience

Knowing your audience is the cornerstone of effective technical writing. Your audience’s level of expertise, background, and needs will shape how you present information. For example, an article aimed at beginners will differ significantly from one intended for advanced users. Conducting audience analysis helps tailor your content to their expectations and comprehension levels.

Tips:

• Create audience personas to visualize your readers.
• Gather feedback from real users to understand their challenges and preferences.
• Adjust your tone, vocabulary, and detail level based on the audience’s expertise.

Writing for Beginners

When writing for beginners, you can include a Pre-requisites section at the beginning to inform the beginner(s) about what tools they need to follow through the article. After that, you can write an Introduction where you would introduce the concept being taught, the relevant technical terms that would come up during the main body of the article, and any relevant piece of information you believe is necessary.

Beginner articles usually start with walking the reader through environment setup, provide codes to copy-paste or steps to replicate a concept, as well as the intended output and how to achieve it. Most articles you find on popular content blogs are beginner-friendly ones.

Writing for Advanced readers

Its a lot difficult writing for advanced users except you are an expert in the subject niche. This is because your audience are people who would rather skim through low-level documentations to figure something out than read an entire article about it. When writing for an advanced audience, you have to cut through lots of obvious definitions, lines of code, procedural instructions, etc.

Advanced articles are usually about explaining how to fix a rare issue, especially since the writer managed to figure the fix out after several attempts, and want to make it easier for other people. As such, there would just be code blocks that may not be preceded by steps to setup an environment or any obvious process that can be learned easily from a Google search. Most of Vitalik’s articles are advanced by default.

2. Master the Subject Matter

A good technical writer must have a strong grasp of the subject they’re writing about. This doesn’t mean you need to be an expert, but you should understand the key concepts, processes, and terminology involved. This knowledge allows you to explain things accurately and confidently.

Tips:

• Collaborate with subject-matter experts (SMEs) to deepen your understanding.
• Engage in self-study through books, online courses, and industry articles.
• Attend workshops, webinars, and conferences relevant to your field.

The best technical writers are usually the ones that work as software engineers in the subject niche they’re writing about.

Most technical writers start out in the space as a means to make extra money off their residual knowledge and expertise in software development. Some are exceptionally good backend engineers, frontend developers, machine learning experts, etc. In order to develop the right lingo, meet fellow colleagues that are potential interviewees, and know the industry standard and trending tools and technology, you need to actually be active in the niche you write about.

For example, suppose you wanted to write on the topic “How to Mitigate Hidden Cloud Costs on AWS.” You could do extensive research on this, but you would likely encounter write-ups by engineering teams from companies that have previously addressed this problem. However, the dates on these write-ups might not be recent—technology evolves rapidly these days. Therefore, you cannot be certain if your research materials are still accurate unless you verify the information yourself or consult a cloud engineer. What are the chances of finding a cloud engineer who is both knowledgeable and available to tinker with their AWS accounts, provide screenshots, and offer code samples for your article?

Essentially, having experience as a software engineer would make this process much easier. You could simply log in to the AWS console, set up your benchmarking requirements, and take the necessary screenshots yourself.

3. Structure Your Content Logically

Logical organization is critical in technical writing. Your content should flow in a way that makes sense to the reader, guiding them through the information without confusion. Use a clear and consistent structure, such as chapters, sections, and subsections.

Tips:

• Start with an outline to plan your document’s structure.
• Use headings and subheadings to break up text and highlight key points.
• Follow a logical progression, such as from general to specific or from problem to solution.

This article is a good example of a well-structured article.

4. Use Clear and Concise Language

Clarity and conciseness are vital in technical writing. Avoid jargon, unnecessary words, and complex sentences. Aim to make your writing as straightforward as possible, ensuring that readers can quickly grasp the information.

Tips:

• Use plain language and define any necessary technical terms.
• Keep sentences short and to the point.
• Avoid passive voice where possible, as active voice is usually clearer.

If there are appropriate technical terms that are used in the niche you are writing for, you should opt to use it. However, if you feel that some of your potential audiences may not understand, then defining it early in the article is the best thing to do.

It might help also to embed links to websites where a term is properly explained, but be careful when you do so. Only embed links to popular sites like Wikipedia.org, and official niche sites like Ethereum.org. If you write for a platform, you should promote containerization (keeping the reader back in the platform) by embedding links to internal write-ups published on the platform itself, to the best of your ability. Most companies love this.

5. Incorporate Visuals Effectively

Visual aids like diagrams, screenshots, and charts can significantly enhance understanding. They provide a visual representation of complex information, making it easier to comprehend.

Tips:

• Use visuals to supplement and clarify text, not replace it.
• Ensure visuals are clear, well-labeled, and relevant.
• Maintain a consistent style for all visuals to avoid confusing the reader.

Research has shown that most people learn visually, so it only makes more sense to reinforce your articles with at least:

1. a cover page / thumbnail
2. an illustrative model of any process that can be put in image format

6. Edit and Revise Thoroughly

Editing and revising are crucial steps in the writing process. They help refine your content, eliminate errors, and improve readability. A well-edited document reflects professionalism and attention to detail.

Tips:

• Take breaks between writing and editing to gain fresh perspective.
• Read your work aloud to catch awkward phrasing and errors.
• Use editing tools and checklists to ensure consistency and accuracy.

If you write for a company, chances are that they’ve paired you to an editor already. Whether that is the case or not, it is very important that you review and redraft your article to fit the reader’s perspective before shouting “Done!”

7. Seek Feedback and Iterate

Feedback from others can provide valuable insights into how your writing is perceived. Be open to constructive criticism and use it to improve your work. Iteration is key to refining your documents.

Tips:

• Share drafts with your editor, colleagues, SMEs, or a trusted peer group.
• Incorporate feedback thoughtfully, balancing suggestions with your judgment.
• Continuously improve your skills through practice and learning.

Again, if you write for a company, your editor or a marketing staff would provide as much feedback on how to improve the write-up. Sometimes, it is important to get feedback as early as possible, especially to confirm that the solution or steps you propose in the article is actually a right one.

8. Stay Updated with Industry Trends

The field of technical writing is constantly evolving with new tools, techniques, and best practices. One of such is the advent of Generative AI, which has revolutionized content creation with a storm. Staying updated helps you maintain a competitive edge and ensure your writing remains relevant and effective.

Tips:

• Follow industry blogs, forums, and social media groups.
• Participate in professional organizations and attend industry events.
• Regularly review and update your skills and knowledge.

On the flip side, you are also expected to stay updated with:

• new technologies in the niche you write in,
• new developments in the tools and technologies from the developers, on the tool/technology you write about, and/or
• feedback from the leading experts and the wider community using those tools and technologies you write about.

It is prevalent to find “Update: “ tags at the top or bottom of some articles, depicting when the author comes back after some time of experimenting, in the advent of a new technology, etc. Documentation Engineers usually publish a newer version of their docs likewise.

9. Develop Strong Research Skills

Good technical writing often involves extensive research. Being able to find reliable information quickly and efficiently is a valuable skill. Proper research underpins the accuracy and credibility of your content.

Tips:

• Use a variety of reputable sources to gather information.
• Evaluate the credibility of your sources carefully.
• Implement findings or your own ideas to make sure they work as intended.
• Document your research process to ensure transparency and traceability.

With the advent of Generative AI, it is much easier now than before to propagate misleading information in your article. The best and most effective way to mitigate that is to practically implement and test out your findings to be sure they work perfectly, before writing about it. Readers are also sensitized to be on defense concerning falsified content, so you should put visual evidence of your testing processes to further convince them.

Conclusion

Becoming a good technical writer requires a combination of skills, knowledge, and practice. By understanding your audience, mastering the subject matter, and honing your writing and editing skills, you can produce clear, concise, and user-friendly technical documentation.

Keep learning, seek feedback, and stay updated with industry trends to continually improve your craft. With dedication and effort, you can excel in the field of technical writing and make complex information accessible to all.