Techincal Writing for Geeks

Technical writing is a form of writing that focuses on explaining complex technical information in a clear and concise manner. It is used to communicate technical information to a specific audience, often in the form of manuals, technical reports, white papers, or other documentation.

This blog will help techies in following work:

• writing good documentation
• writing technical emails to colleagues
• taking effective notes
• and more…

A little profiency in English is enough to grasp the basic concept of technical writing.

Use Active Voice

Majority of technical writing should be in active voice.

Active Voice Sentence = actor + verb + target

Example: Prathamesh wrote the report.

Passive Voice = target + verb + actor

Example: The report was written by Prathamesh.

In the active voice sentence, the subject “Prathamesh” performs the action of writing the report. In the passive voice sentence, the subject of the sentence is the report, and the action is being performed upon it by Prathamesh.

Active voice provides the following advantages:

• Readers mentally process passive voice to active voice. Use active voice to skip the processing part and land directly on point.
• Active voice sentences is generally shorter than passive voice sentences.

Be bold - be active

Clear Sentences

As comedy writers aims for funny results. Technical writers seeks for the clearest results. In technical writing, clarity takes precedence over all other rules.

Use strong verbs

Will we ever serve our loving guests with stale food? No! right? Similarly our readers should not be served with repetitive mild verbs.

Reduce imprecise, weak, or generic verbs, such as the following:

• forms of be: is, are, am, was, were, etc.
• occur
• happen

Using mild verbs

When a variable declaration doesn’t have a datatype, a compiler error happens.

Using strong verbs

When a variable declaration doesn’t specify a datatype, the compiler generates an error message.

Avoid unnecessary words

For example consider the following sentence:

There is no guarantee that the updates will be received in sequential order.

The above sentence can also be written as:

Clients might not receive the updates in sequential order.

Here we replaced ‘There is’ with a meaningful subject (clients) which creates a clearer experience for the reader.

Short Sentences

Shorter code easy to read and maintain. Similarly, short documentation is faster to read and easy to understand. Readers prefer shorter sentences to longer ones. However, many writers try to prove their intelligence by writing unnecessarily long sentences

One sentence, one idea💡

Every sentence should should be focused on one idea. Long sentences with multiple ideas are generally harder to understand.

Consider the following long sentence:

• Liquid precipitation on the Iberian Peninsula is primarily deposited on flat, non-mountainous regions.

• The efficiency of Web browsers in displaying graphic images is in direct correlation to the disk resources required by the aforementioned graphic images.

Breaking the long sentence into a succession of single-idea sentences yields the following result:

• The rain in Spain falls mainly on the plain.

• Web browsers display small graphic files quicker than big graphic files.

Short : sweet

Be consise

Eliminate or reduce extraneous words

Convert some long sentences to bullet points

Long sentence:

As part of our marketing strategy, we plan to conduct market research, analyze consumer behavior and preferences, develop a comprehensive advertising campaign, establish partnerships with key influencers in our industry, and leverage social media platforms to promote our brand and engage with our audience.

Sentence converted to bullet points:

We perform the following tasks as a part of our marketing strategy:

• Conduct market research
• Analyze consumer behavior and preferences
• Develop a comprehensive advertising campaign
• Establish partnerships with key influencers in our industry
• Leverage social media platforms to promote our brand and engage with - our audience.

Lists and tables

Start numbered list items with imperative verbs

An imperative verb is a command, such as open or select. For example, notice how all of the items in the following parallel numbered list begin with an imperative verb:

1. Set the target platform to Any iOS Device.
2. Wait for the index processing.
3. Go to Product > Archive.

Create useful tables

Tables are important because they provide a visual representation of complex information, making it easier to understand and analyze.

Here are some specific reasons why tables are important:

• Clarity
• Comparison
• Structure
• Efficiency
• Accuracy

Consider the following guidelines when creating tables:

• Label each column with a meaningful header. Don’t make readers guess what each column holds.
• Avoid putting too much text into a table cell. If a table cell holds more than two sentences, ask yourself whether that information belongs in some other format.
• Although different columns can hold different types of data, strive for parallelism within individual columns. For instance, the cells within a particular table column should not be a mixture of numerical data and famous circus performers.

For Example:

The project plan includes the following tasks: developing the project scope and objectives, identifying project stakeholders and their roles and creating a project schedule with key milestones

Converted to table:

The following table summarizes the projects plan:

Overall, tables can be an effective tool for presenting complex information in a clear and concise manner, making it easier for readers to understand and interpret.

Introduce each list or table

Give the list or table context. Terminate the introductory sentence with a colon rather than a period.

Although not a requirement, we recommend putting the word following into the introductory sentence. For example, consider the following introductory sentences:

• The following list identifies key performance parameters:
• Take the following steps to install the dart package:
• The following table summarizes our product’s features against our key competitors’ features:

Paragraphs

In technical writing, paragraphs serve the same purpose as in other types of writing - to organize ideas and present them in a coherent and logical way.

Write a great opening sentence

Good opening sentences establish the paragraph’s central point. A great opening sentence for a paragraph should be clear, concise, and engaging, providing the reader with a clear understanding of what the paragraph is about and why it is important.

For example, the following paragraph features an effective opening sentence:

In recent years, advances in artificial intelligence and machine learning have revolutionized the way that businesses approach data analysis. You probably interact with artificial intelligence on a daily basis and don’t even realize it.

Answer what, why, and how

Good paragraphs answer the following three questions:

1. What are you trying to tell your reader?
2. Why is it important for the reader to know this?
3. How should the reader use this knowledge? Alternatively, how should the reader know your point to be true?

Example

What:

Productivity tools can help individuals and organizations work more efficiently and effectively by automating repetitive tasks and streamlining workflows.

Why:

In today’s fast-paced business environment, time is a precious commodity. Productivity tools can help individuals and organizations make the most of their time by freeing them up from tedious or time-consuming tasks. By automating these tasks, individuals can focus on more important and higher-value activities that can drive business growth and success.

How:

There are a wide variety of productivity tools available today, ranging from simple task lists to complex project management software. Examples of popular productivity tools include project management software like Asana or Trello, automation tools like Zapier, and communication tools like Slack or Microsoft Teams.

Documents

State your document’s scope

A good document begins by defining its scope.

This document is aimed at the following audiences:

• software engineers
• program managers

Summarize key points at the start

Professional writers focus considerable energy on page one to increase the odds of readers making it to page two. However, the start of any long document is the hardest page to write. Be prepared to revise page one many times.

Write for your audience

Answering the following questions helps you determine what your document should contain:

• Who is your target audience?
• What is your target audience’s goal? Why are they reading this document?
• What do your readers already know before they read your document?
• What should your readers know or be able to do after they read your document?

Overall, a good technical writing should be clear, concise, and free of unnecessary jargon or technical terms that may be unfamiliar to the reader. It should also be well-organized, with headings, subheadings, and bullet points used to break up long paragraphs and make the information more accessible. Graphics and diagrams may also be used to enhance understanding.

This blog is also available on dev.to