Intro to technical writing

Technical writing is a highly valued skill today, and the demand for technical writers will keep growing because of rapid advancements in science and technology.

Whether you’re new to technical writing or just trying to improve your writing skills, get ready for a rewarding journey!

So, buckle up as we delve into the essentials of technical writing!

What is technical writing?#

Technical writing is a specialized field that delivers clear and understandable instructions, directions, guidance, or information to a specific audience through documentation.

It mainly aims to break down hard concepts or information into simple concepts easily understood by the targeted audience.

In simple terms, technical writing gives people clear instructions so they can easily use things or solve problems.

Different Types of Technical Writing#

Technical writing involves creating detailed instructions, step-by-step guides, or information about products or technology. A good technical writer needs to know the subject well so that their audience can easily understand the content.

For example, if a technical writer doesn’t understand programming, they won’t be able to write clear API documentation. API documentation requires knowledge of programming concepts like data types, arrays, and objects.

Mastering Technical Writing:

1. Understand what
you're writing about.
2. Determine who it's for.
3. Keep it concise.
4. Make it user-friendly.
5. Refine, review, revise.

Make it your mission to make the complex simple. The mysterious, known. pic.twitter.com/Ar76RE8AtK

— Wisdom Nwokocha 🥑 (@Joklinztech) January 15, 2024

Common types of technical documentation:#

1. Technical reports:#

These documents provide detailed results of projects, research findings, investigations, and experiments in a specified field. They may include recommendations and conclusions.

The key elements of technical reports are the title, introduction, summary, experimental details, results and discussions, body, and conclusion.

An example of a technical report is the Complete Engineering and Economics of Solar Photovoltaic Hybrid Power System .

2. Installation Guides:#

These documents assist users or customers in installing software, products, or systems correctly.

Installation guides give general instructions about products or software and step-by-step instructions for installation. Examples

• Home appliances
• Computer software
• Etc.

An example is the Visual Studio Code set up guide that provides detailed step-by-step instructions for installing VScode on your computer.

3. User manuals:#

These are also known as user guides or instruction manuals. It is a written document that provides information on product features, step-by-step guides, product functionality, and troubleshooting instructions in case of issues.

An example of a user manual is WhatsApp User Manual.

4. Technical Specifications:#

These are manuals or documents that detail a product’s technical aspects. They also provide vital information about product development.

For instance, in software development, the technical specification manual provides essential information about an app, such as the problems it is solving, the features of the app, implementation plans, software’s architecture, programming languages, and libraries to be used for developing the app, the hardware requirement and testing procedures.

An example of a technical specification document is the Software Requirements Specification document.

5. API Documentation:#

These documents guide users on integrating an application programming interface(API). It includes details on endpoints, authentication, request and response formats.

An example is the Paystack API documentation.

6. Technical proposal:#

These are well-written documents that outline details of a proposed technical project, product, solution, and so on.

The primary goal of a technical proposal is to show actionable plans to stakeholders or decision-makers, persuading them to accept and support the proposed project.

For instance, if a writer proposes a project to a company, the proposal should provide an overview, scope, target audience, and other essential project details.

Click on this Technical Proposal Template to learn how to structure your technical proposal.

7. White Papers:#

These documents provide comprehensive analysis, information, or recommendations on a specific topic, product, or technology.

White papers are used across various fields to provide in-depth reports to aid understanding and decision-making.

An example of a white paper is the WhatsApp Security White Paper.

8. Release notes:#

These are documents that inform users, developers, or administrators about recent features of a software product, bug fixes, or any other update.

For example, a software company may introduce new features in their product, such as dark mood support, improved mobile responsiveness, streamlined navigation, and bug fixes, through release notes.

The Google Cloud Release Note is an example of a release note.

9. Online help:#

These digital documents provide instructions, guidance, or information to assist users in effectively using products.

For example, Google Chrome’s online help informs users about the browser, new features, and issues reporting.

Online help enhances the user experience by offering troubleshooting guides and product insights.

Audience for technical documentation#

To become an effective technical writer, you must know your audience. Your audience is the people for whom you are writing.

Understanding your audience is crucial because it determines what and how you communicate, allowing you to convey your message in a way that resonates with them. How can you know your audience?

You can understand your audience by asking yourself who they are. Consider questions like: Are my audience software developers, engineers, or technicians?

Are they beginners or experts in their field? Why are they reading my documentation? What do they expect from it?

Answering these questions will help you determine your target audience and guide you in tailoring your writing style and content to meet their needs effectively.

For instance, you want to write an article titled: Introduction to technical writing.

Some questions you need to ask yourself:

If you answer the questions above, this will help your readers understand this topic very well.

Now, let’s use the questions above to know your target audience.

• Who am I writing for? Technical writers,

• What is their level of expertise? Beginners

• What do they expect from my article? They expect this article to give a comprehensive overview of technical writing, the audience for technical writing, types of technical documentation, tools and software for technical writing, and so on.

Purpose for Technical Documentation#

There are numerous reasons for writing technical documentation. The purpose of technical documentation includes:

1. Guidance:#

It provides comprehensive and easy-to-follow guidance, instructions, and directions on using a product, software, or service.

2. Reference:#

It serves as reference materials for product or service users, as it details a product’s different features.

3. Training materials:#

Technical documentation can be used to train new users, employees, or technicians.

4. Updates:#

It is used by companies to provide information about upgrades in their product or service.

5. Troubleshooting:#

Technical documentation provides troubleshooting guides that can help users when they encounter a problem while using a product.

Technical writing process#

There are five technical writing steps.

Figure 1: Technical writing steps

1. Plan:#

A popular saying goes, “If you fail to plan, you plan to fail”. This principle applies to technical writing as well.

Before you begin writing, planning and preparing for your topic is essential. Planning can be as straightforward as creating bullet points outlining the project you want to cover.

This mental exercise will help you address important questions about your audience.

At the planning stage, you need to determine your document’s purpose and scope, writing style, and length. A well-thought-out plan saves time and ensures a successful outcome.

2. Structure:#

Structure serves as the backbone of your documentation, providing the necessary organization for the hierarchy of your document.

You lay a framework for how your document will unfold at this stage. For instance, creating a table of contents enhances the organization of your content and mentally prepares you for the writing journey.

It is also important to note that the structure of your document is not a rigid constraint; it evolves as you write, allowing for adaptability as you write.

3. Research:#

This stage is the foundational step in the documentation process. It involves getting all the information you need for your writing.

This includes reading relevant documents, watching videos, and interviewing experts in the field.

For instance, if you want to write about Google Chrome, you will need to read Google Chrome documentation and other relevant documents to know about its features and how they work. Watching tutorial videos, if needed, will help you gain more insights.

Taking this approach will enable you to give your audience detailed and up-to-date information about the Google Chrome browser.

4. Write:#

In this stage, you will put all the information you have gathered into a logical and cohesive document. You must also write simply, clearly, and concisely, always keeping your audience in mind.

Adapt your language to resonate with the specific needs of your readers. For instance, if you are writing for beginners, focus on clarity and provide explanations to ensure solid understanding.

For experts, delve into technical details assuming a deeper knowledge base.

Remember that the document’s structure established in the earlier stage is your guide.

Ensure seamless navigation through the content by adhering to this structure.

For clarity, incorporate images, code snippets, tables, screenshots, and diagrams in your document as it helps your readers comprehend the message you are passing faster.

As you craft your document, envision your audience engaging with the material and tailor your writing to meet their expectations.

5. Review:#

This stage is the polishing stage. In this stage, your goal is to ensure the overall quality of your document. Start with reviewing your document.

As you review, pay close attention to maintaining a consistent writing style, correcting grammatical errors, and addressing misspelled words.

Next, consider seeking the input of experts or colleagues in the field to review your document formally.

The goal of this stage is not just error correction but the refinement of your document to meet the highest standard of clarity and professionalism.

6. Publish:#

This stage is the final step in releasing your document to reach your intended audience.

Platforms like Medium, Hashnode, Devrel, and other social media platforms can serve as avenues for sharing your work with the world.

Consider the nature of your content and your target audience when deciding the suitable platform for publication.

Answer the following questions.