How to Write Technical Texts

Narrative Style

The narrative style should be relaxed, without flirtation, memes, or jokes.

---

Before

Did you know that JavaScript has as many as 8 data types? Oh, yes, this language is full of surprises! Among them are not only familiar strings and numbers but also such exotic types as Symbol and BigInt.

Don’t panic! In this article, we will look at all data types.

Each data type is the key to a new mystery that JavaScript is ready to offer you. Let’s dive into this exciting journey through the world of data, and who knows what wonders await us along the way!

This example is highly exaggerated, but similar sentences are found in programmers’ texts.

This style is not suitable for educational content. Jokes in the text distract from the content and are annoying. Let’s fix it:

---

After

JavaScript has 8 data types, including strings, numbers, Symbol, and BigInt.

Verbal Nouns

Verbal nouns are nouns that are formed from verbs and denote an action, process, or result. They are usually easy to replace with a verb.

The problem with verbal nouns is that they overload the text, remove action from it, and make the text inanimate, dry, and boring.

An example of a text with verbal nouns:

---

Before

Integrating Nuxt.js into frontend development projects facilitates the creation of universal applications. Simplifying setup and configuration makes project startup quick.

Using server-side rendering enhances performance and improves SEO.

Integration with Vue.js aids in the development of interactive user interfaces.

Let’s replace verbal nouns with verbs and breathe life into this text:

---

After

Nuxt.js simplifies the creation of universal frontend applications. Quick project startup is achieved by a simple configuration setup.

Server-side rendering speeds up page loading and improves SEO.

Thanks to Vue.js compatibility, developers can easily create interactive user interfaces.

Do not use verbal nouns.

Passive Voice

The passive voice shows that the action is not done by the subject, but that the action is done over the subject. This style is similar to the language of officials.

The Passive Voice makes reading difficult and is usually easily replaced by the Active Voice.

The active voice makes sentences more direct and clear. Let’s look at an example:

---

Before

GraphQL was developed by Facebook to simplify the data exchange processes between client and server.

It is based on the use of a typed query system that allows clients to define exactly what data they need. As a result, redundant data loading has been significantly reduced and client application performance has been improved.

---

After

Facebook developed GraphQL to simplify data exchange between client and server.

GraphQL uses a typed query system that allows the client to specify exactly what data it needs. This eliminates redundant data loading and improves client application performance.

To read a sentence with a passive voice, extra attention is paid to figure out who did what. Such sentences seem inanimate.

It is desirable to get rid of it.

The Imperative Mood

The imperative mood adds dynamics to the text, stimulates action, and is used to address the reader directly.

This style of addressing the reader is suitable for writing instructions and manuals, where it is important to give clear and understandable instructions.

---

Before

A Vue project can be initialized using the following command:

Bash

npm create vue@latest

---

After

Run the command to create a project with Vue:

Bash

npm create vue@latest

Also, the imperative mood allows you to make your thoughts short.

Use the imperative mood.

Paragraphs

Divide the text into paragraphs. Paragraphs bring order to the text.

One thought is one paragraph.

A paragraph begins with the main idea. The first sentence of the paragraph is necessary for the reader to understand what the paragraph is about. If the beginning of the paragraph doesn’t appeal to the reader, they move on to read the next paragraph. Delete anything that does not relate to the main idea of the paragraph.

Short Sentences

Avoid long sentences. In life, we communicate in short sentences. When a text is close to spoken language, it is easier to read and understand.

---

Before

Long sentences make us spend more time parsing complex structures, which can lead to fatigue and confusion, especially if the sentences contain many subordinate and additional parts, which makes the process of information perception much more complex and less effective compared to short and concise statements, where each thought is clearly separated and presented in the most concise form, which undoubtedly facilitates reading and understanding of the text.

---

After

Short sentences read easily. They are quick and clear. Each idea is separate. This helps with comprehension. Our brains are not overloaded. Information is absorbed faster.

Syntax

Simplify syntax in your text.

We pause at each punctuation mark when we read text.

The more commas there are in a sentence, the harder it is to read. If you are short of breath when reading a sentence, it means it is a long sentence. Therefore, get rid of participial turns, introductory words, dashes or colons, and explanations in brackets.

To get a good text, you need to read it aloud. If we stumble when we read a text, then the text needs to be simplified.

Headings and Lists

Just like code, technical texts should be modular.

Highlight subheadings and bulleted lists to make it easy to find what you need in the text.

A well-structured text makes the learning process more efficient and enjoyable.

Writing the Introduction

The reader needs to understand if it is worth their time to read the article. Therefore, the introduction can begin by explaining the usefulness of the article. Answer the reader’s questions:

• What concept will I be introduced to in the article?
• What will I be able to do after reading the article?
• Why is it necessary?

Writing the Conclusion

The task of the conclusion is to draw conclusions and give practical advice on how to use the material studied.

In the conclusion, you can give references to additional materials for further study of the topic, and express your personal opinion about the material.

Editing

Accessibility

Minimize the number of terms and abbreviations if possible. Unfamiliar terms are repulsive to newcomers, and their abundance reduces motivation to learn content.

If complex terms are used in the text — explain them. If another term is used in the explanation of a term, explain it in a chain.

Remember, readers are people with different levels of technical knowledge. Make texts accessible to everyone.

Explain cause and effect. In technical texts, it is important not only to show how something is done but also why it is important.

It is important not to slip into describing very simple things.

---

An input field is a functional component that gives users the ability to enter values using the keyboard.

Which things are worth explaining and which are not, you have to decide for yourself. There is such a thing as the curse of knowledge. This is when a person who knows a topic well cannot easily explain it to newcomers because he or she cannot imagine himself or herself in their shoes.

Concision

We don’t have a lot of free time. We all want to get value from content as quickly as possible.

Long introductions distract from the essence of the text and bore the reader. Keep them short in the first place. To keep your audience’s attention, keep your thoughts short and get to the point as quickly as possible.

The phrases “pay attention”, “it is worth mentioning”, “it is important to specify that” disrupt the natural flow of the text and interrupt the reader’s attention. They should not be in the text.

Brevity

If the text can be shortened, it should be shortened. Do not use introductory words, participles, de-particles, verbs in the passive voice, or synonyms when describing.

---

Before

The use of version control systems such as Git represents an important and essential aspect of software development, as they allow developers to track and manage changes to code. As such, it is a vital tool for collaboration and effective project management.

---

After

Git is a tool for tracking code changes and collaborating on projects.

Another example:

---

Before

Functional programming is a programming paradigm that strives to write code where all functions have no side effects and data is not mutated.

---

After

Functional programming is a style of coding without side effects or data mutation.

After writing a text, always take time to edit it, and read the text aloud. The text may be overloaded with unnecessary words.

Objectivity

Never give biased assessments. Vague language should be removed or supported by facts.

For example:

---

Before

TinyJS is a fast and lightweight state management library for multiple frameworks.

This sentence sounds unconvincing precisely because of the lack of evidence. Tell the truth, even if it is inconvenient:

---

After

TinyJS is a lightweight library (2 kB) for state management in React and Preact.

Benchmarks:

…

Clearness

Ambiguity in text can create confusion in the minds of novice developers. Be unambiguous and straightforward.

---

Before

TypeScript offers strict typing, which can be useful for increasing code stability and reliability.

---

After

TypeScript provides strict typing to improve code stability.

Evaluations

Refuse from subjective evaluations, such things undermine the reader’s trust. There should be no biased and unfounded judgments in the text. Any evaluative judgments should be accompanied by evidence.

---

React is by far the best framework out there.

---

Everyone knows what OOP is.

Visualization

Diagrams, schemes, screenshots, and code samples improve understanding of technical details. They are easier to read than text.

---

Before

To create a gradient background, you need to use the linear gradient function in CSS, specifying the starting and ending colors and the direction of the gradient.

If we used code, the text would become clear:

---

After

Create a gradient background in CSS:

CSS

.section {
  background: linear-gradient(direction, start-color, end-color);
}

• direction: gradient direction,
• start-color: start color,
• end-color: end color.

Variables

Expressive variable names allow you to write code without comments. Choose variable names responsibly.

You should not name variables with one letter unless it is a local variable in a loop.

If the variable’s value is an object or primitive, variables should be denoted by a noun:

• user
• age

If an array, plural noun:

• users.

Function names must begin with a verb:

• getUserInfo()
• downloadCSV().

For event handlers, the on or handle prefix is usually used:

• onSubmit.
• handleNameChange.

Logical values usually begin with the words is or has:

• isAdmin.
• hasValue.

Never use magic numbers. They are called magic because you can’t tell where they came from or what they mean.

---

Before

JavaScript

let blockSize = 20 * 8

To get rid of magic numbers, you just need to put them into variables and the code will become clear:

---

After

JavaScript

let elementWidth = 20
let numberOfElements = 8
let blockSize = elementWidth * numberOfElements

Imports

When using code from a module for the first time, show its import. Otherwise, the reader will copy your code and be surprised to find that it doesn’t work.

---

Before

JavaScript

export let getDirname = () => {
  let filename = url.fileURLToPath(import.meta.url)
  return path.dirname(filename)
}

---

After

JavaScript

import path from 'node:path'
import url from 'node:url'

export let getDirname = () => {
  let filename = url.fileURLToPath(import.meta.url)
  return path.dirname(filename)
}

Simplicity

Code examples are important, they make the text practical and useful.

If the text explains a complex concept, start with simple code examples and gradually go deeper by adding details or functionality.

Strive to keep the code clear and simple. Complex designs intimidate readers.

If the sample code is still large and complex, add comments to the code. And be sure to explain additionally how it works. Comments to the code do not replace the text.

Commands

After executing commands in the terminal, the expected result should always be shown.

---

To install NodeJS, run the command:

Bash

brew install node

Make sure that NodeJS has been successfully installed:

Bash

node -v

Anti-patterns

If there are examples of how to write code you don’t need to write, it’s worth highlighting. For example, conditions that lead program execution to an infinite loop.

Relevance

Regularly update texts that have already been published. Technology changes quickly, so it’s important to keep your content current.

Always make sure that code samples work.

Nothing is more frustrating than non-working or irrelevant code samples or outdated information.