by Communication. Although a difficult concept to define, it’s easy to recognize its relevance and impact on the success of any goal. In an attempt to do it, we could say that communication is a way to soften the barrier between the self and the other, sharing motivation and reasoning with one or many interlocutors.
Yuval Harari, in his book "Sapiens: A Brief History of Humankind", says that even though the formation of a shared language played a relevant role in our development, this is not something that sets the sapiens species apart from the other ones. What allowed us to make an exponential leap on it during the so-called Cognitive Revolution was the ability to talk about our shared beliefs, myths, religions, and abstract concepts; and cooperate toward larger aims somehow united by those beliefs.
As human societies emerged and developed, a motivation to transmit, persist and expand communication emerged with it, requiring a way to represent language non vocally, through what we call writing. Writing comes with the advantage of being more time resistant, but the disadvantage of making it harder to be accurate while attempting to express tone and reasoning, especially when talking about those concepts that require abstract thinking from the reader, like imagination, generalization, and the definition and recognition of patterns.
Expressing such concepts is an inherent part of technical writing, a discipline focused on making complex subjects simpler to understand and recognize why and how it applies to the reader’s goal. Observe that this has a lot in common with writing good quality code. We attempt to make the concepts explicit while balancing them by abstracting complex parts, so minding them is unnecessary.
In this article we’re going to discuss some guidelines to reach effective technical writing, points to observe while preparing the subject, during the writing process, and after it, when performing self-reviewing.
Don’t go headfirst: start by creating interest and bonding
Many writers attempt to tackle the gist of the subject right at the beginning for fear of padding out the text, don’t let yourself fall for that. Even though padding out is a real problem, it is very different from writing a proper introduction to the matter you will tackle.
Digging right into the content can confuse the reader that is not sure yet if they are even interested in the subject and make the text look vague or shallow. So take some time to create interest and put your personality into the text, allowing the readers to bond and identify themselves with it. I could have started this article straight into the "In this article we’re going to discuss…" part, but how would a reader know what will be the tone of the text? How would they know what in technical writing makes it difficult or how it relates to programming? These topics are important to involve the reader, so don’t skip the introduction.
Think about the introduction of your text as you would introduce yourself into a conversation with strangers. You don’t just jump into the conversation without making it clear why you understand what they are talking about, nor start by talking about your preferred pizza toppings, or what the color of your toothbrush is… unless it’s an actual conversation about toothbrushes colors, of course.
Define a focus
I admit it: it’s tempting to talk about many subjects in the same text. Sometimes we’re just too excited with all the shiny things we’ve discovered and developed recently and want to cramp it in the same article. I’ve been there, but the focus is important. Texts that are too long are just like that infinite series of books you’re promising yourself for years that you are going to read, but we all know you are never reading it: people will fear they will forget some important part by the time they get to the middle of it. So instead of writing texts that are too long, sympathize with your reader and focus the text into a digestible piece, in a way that they can read it, sleep on it, and still feel that they learned something valuable.
Sometimes the subject is just too large, yes, but in those moments, choose to plan a series of texts, finish each part with a good closure but make it clear that there is more in the subject to talk about. When defining what will be part of the series, remember that each of them deserves an introduction, even if it’s a smaller one from the second part and up, and make the reading order as concise as possible. Nobody wants to get to the third article of the series and notice that they are not understanding something because they skipped an important part.
Prepare yourself and be honest
Ok, now you have the exact focus of the text you’re going to write about, but are you prepared to talk about it? I don’t mean to discourage you to write with this question. We all can talk about interesting stuff and teach something even if we’re not well experienced in the subject yet, but you have to be honest with your reader.
Making your relation and experience with the subject clear is very important, and by that, I don’t mean "show your credentials" but rather talk in which context you got to the conclusions you are going to make, avoid expressions like "best practices" (as "best" is something relative and possibly time-sensitive), prefer to say that what you’re showing and telling is based on your experience and/or research.
Also, regardless of your experience, prepare yourself when you are going to formulate the text. Read other pieces that talk about the same subject, the official documentation, surround yourself with the topic, and don’t feel pressured to make it look like all the ideas in the article are originally yours: we all stand on the shoulders of giants. Have you ever heard of the concept of "learning by teaching"? That is part of it. By improving yourself and researching a topic to teach someone, you end up learning more about it, making you more capable of explaining the matter of the text effectively and accurately.
Reading flow and structure
The next aspect of good technical writing is considering the reading flow and how the ideas will lay and depend on each other. Avoid giving details of subjects you have not mentioned, using acronyms or terms that were not explained at the point yet, or even making the reader feel like they should read some part ahead and then go back to where they were before. In summary: don’t break the reading flow. Instead, try to make a soft gradient of concepts where every paragraph the reader reaches accumulates the knowledge they will need to read the next one.
For technical terms that require a lengthy explanation but will appear ahead, prefer to use a simplified version of it, free of technical jargon, which only hints at the concept. This way, when you finally get to explain the term, the reader will already have some notion of how it relates to the rest of the text. For example: let’s say you want to talk about state management. That includes talking about the concept of "local state". Instead of beginning with "local state is […]", you should simply call it "data" while involving the reader in the subject where they can recognize the presence of this so-called "data" in their daily work. When they are already familiar with the concept and how it relates to the text you can finally say ‘ok, so this is what we call "local state"’ and then give a deeper explanation.
If the subject of the text contains different levels of complexity that escalate, prefer to write following the complexity ladder. Avoid getting too-complex approaches right away and try to introduce each step of the discussion gradually. For example, you can start explaining a technique that can be implemented in a very naive but simpler, more explicit way, even if it has caveats. Once you’re able to make the technique itself and its advantages clear, you can now mention the tradeoffs of following that implementation and go to the next complexity level, tackling each of the caveats of the previous one and so on until you get the full-blown solution. This step-by-step might even involve manually implementing something that a reusable library already does for us. As long as we do not get too deep into re-implementing it, and it adds to the understanding of each step, go for it.
It is also important to make the structure of the text clear to the reader. They should be able to understand which part depends on each other, if it is a progression or an alternative to another one, and where they can stop for a minute to make sure they grasp what was read until that point. Formatting is a great tool to accomplish that: create sections with titles and use different headings to make the structure and hierarchy clear.
Every problem has a cause
A lot of technical writing is on how to tackle a specific kind of problem. Sometimes it’s a bug, a challenge that needs to be overcome, or some difficulty inherently present when dealing with some class of task, but they all have something in common: a cause.
Going over the reason for a problem is as important as talking about the solution. That will make it clear to the reader if they are the actual target of the article and more: it will show why they can trust the solution you are proposing, why it solves the problem, and teach them more deeply.
While showing the reason, use every resource you have to make it clear, including links to the documentation, Github issues, repositories that the reader can clone and run on their computer, images, and so on. You can use formatting there to highlight the key parts as well, but use it sparingly: when everything looks important, nothing looks important.
Remember to show the cause for the problem before showing the solution. The reason for it is the same as why bands keep the most famous songs at the end of a show: they want people to enjoy the whole thing, including songs they might not know yet. If you show the solution and leave the cause to the end, people will end up reading the solution and leaving the rest unread, learning less than you attempted to teach.
Don’t make your reader feel dumb
As aforementioned in the article, your main goal is to inform your reader, and make them feel smarter as they go through your text; make them have "aha!" moments, not the other way around. While writing, you should pay attention so your tone and language do not make your reader feel dumb or ashamed for not knowing something. This might cause them to be reluctant to admit they don’t know a piece of information, thus making them keep reading your text without the proper base necessary to take advantage of the content.
There are two main ways you should pay attention not to make your reader feel dumb:
The first is avoiding assuming the reader knows something without ever mentioning it. Many people don’t know what they don’t know, so how would your reader know they are lacking some knowledge if you treat it as an implicit dependency of your text?
The second is to avoid mentioning lack of mandatory knowledge as something unacceptable. Avoid expressions like "as you should already know", "as you know" or even "obviously". The mentioned piece of knowledge may be obvious to the writer but not to the reader. If they feel ashamed for not knowing, they will either quit reading your article or keep reading along with a high chance of misunderstanding it, which won’t accomplish the goal of communication of softening the barrier between the self and the other.
For both cases, the recommendation is to introduce or guide the reader to that requirement. A good strategy is to mention the need for some previous knowledge, like: "For this article, it’s expected that you have some experience with JavaScript higher-order functions. You can read about them here" with a link to the official documentation. Another one, if it’s something that does not take long to give a brief introduction, is writing the knowledge directly in the text, while later adding a link or extra reference in case the user thinks that was not enough for them to grasp it. Example: "Higher-order functions are functions that return or/and receive other functions as arguments and depend on native language support, which JavaScript does. You can read more about them here".
Regardless of how you decide to introduce the requirements for reading your article, doing so gently will give you more freedom to talk about the subject, with a higher chance that the reader will understand what you’re trying to teach them, especially with advanced topics.
Show proper examples
A good part of technical writing contains mentions or examples of code to explain a specific scenario or to exemplify how to use some technique or technology. When writing examples, avoid being too hypothetical, or naming variables like "foo" and "bar"; help your reader visualize what you’re trying to show them situations they can relate with. Non-ironically, let’s show how to give a good example with a couple of examples as well.
Let’s start with this piece of code:
interface FooInterface {
getValue(): Promise<number>;
setValue(value: number): Promise<void>;
}
class BarImplementation implements FooInterface {
private value: number;
async getValue() {
return this.value;
}
async setValue(value: number) {
this.value = value;
}
}
class BazImplementation implements FooInterface {
getValue() {
return fetch('/value').then(r => r.json());
}
async setValue(value: number) {
await fetch('/value', { method: 'POST', body: value });
}
}
class MyExampleClass {
constructor(private foo: FooInterface) {}
async incrementValue() {
const value = await this.foo.getValue();
await this.foo.setValue(value + 1);
}
}
const object = new MyExampleClass(new BarImplementation())
const object = new MyExampleClass(new BazImplementation())
If you see this code, can you quickly understand what I’m trying to show there? If not, I’ll tell you: it was the Strategy design pattern. But now you know what it’s meant to be, do you see in this example something similar to what you do in your daily work that makes you understand in which kind of situation you would use this design pattern? If you never used this pattern before, the answer will probably be no, and that’s fine because this example sucks. Let’s try to improve it. I will show something that you might have a higher chance of relating to:
// tokenStorage.ts
interface TokenStorage {
getToken(): string | null;
setToken(value: string): void;
}
// cookieTokenStorage.ts
import Cookies from 'js-cookie';
class CookiesTokenStorage implements TokenStorage {
getToken() {
return Cookies.get('auth_token');
}
async setToken(value: string) {
Cookies.set('auth_token', value);
}
}
// localTokenStorage.js
class LocalTokenStorage implements TokenStorage {
getToken() {
return localStorage.getItem('auth_token');
}
setToken(value: string) {
localStorage.setItem('auth_token', value);
}
}
// authentication.ts
class Authentication {
constructor(private tokenStorage: TokenStorage) {}
ensureAuthentication(token: string): string {
const currentToken = this.tokenStorage.getToken();
if(currentToken) {
return currentToken;
}
this.tokenStorage.setToken(token);
return token;
}
}
// you can change the storage strategy freely as long as they implement the same interface:
const authentication = new Authentication(new CookiesTokenStorage());
const authentication = new Authentication(new LocalTokenStorage());
A little better, right? At this point, even if you never heard of the Strategy pattern or you don’t get how it works, you might at least be able to recognize some terms used in the example, like cookies, local storage, or authentication. You might even know how these things are used and this would make the example even clearer to you. Whenever you’re giving an example, try to replicate a small portion of what your reader might already have some familiarity with, instead of dumbing down the example prefer to take the hypothetical part out of their way and let them focus on the important aspect of the example backed up by their own life experiences.
Language and grammar
We got to a serious point now: you have to make sure you’re using the language properly and correct grammar. By no means do I intend to say that you should be formal or that you should sound like a 15th-century philosopher, no. But ensuring your sentences follow the syntax and the semantics of the language you’re writing in is important to guarantee your readers understand you correctly.
Understandably, sometimes we make mistakes, especially if we’re not using our mother tongue, but if we intend to transmit any information we have to make sure we are expressing ourselves correctly. When writing something in a different language some people find it easier to write first in their mother tongue and then translate it. That is fine, but if you choose to do it, pay attention while using expressions that are very specific to the original language, as they might not translate properly. If that’s the case, you should check if they have a more idiomatic way to say it. We even have an example of that in this very text! The expression for "padding out a text" that I used before would be something like "stuffing sausage" in my mother tongue – Brazilian Portuguese – but it’s not what people use in English. So before using this term, I looked up how people say it in English.
Of course, there will be a process of reviewing the text, which we will mention later in this article, but build the habit of questioning the way you express ideas as you write the text, as you have the context of each sentence fresh in your mind. Also, don’t hesitate to use tools that check your grammar and the way you express ideas, like Grammarly (I swear this is not a sponsored article, the tool is just too good not to mention). Your readers will thank you later.
Sometimes you’re documenting it
Technical writing is not just about writing articles and tutorials. You may be writing the actual documentation of some technology. This gives you a higher level of freedom because you can now link to other parts of the documentation, expand some subjects on a separate page, and even create a dedicated set of documents for each version of the given technology. However, this comes with a heavy responsibility: you’re now the official source of truth about the thing you’re writing.
Being in this position requires your level of detail to be as deep as possible. Your readers should be able to get to your text and know where to go from there, and how to follow the steps to have that technology work as expected, they should trust you. I’ve seen cases where third-party tutorials were a source of documentation more reliable than the official documentation of a tool, and I’m going to tell you: it does not look good on them. It sounds like the people that developed the technology don’t give it the proper attention.
When documenting something, the most critical part is the flow. There should be a clear starting point for your reader, the capabilities of the subject should be clear, and the title of the sections and pages should be familiar to people looking for it. Don’t forget to mention known bugs and troubleshooting, especially for cases where it is easy for people to make mistakes. They can get mad when something goes wrong, and you, the developer, will be the first one to be blamed.
Wrap it up and add references
I’m not sure about you, but I always thought that songs that end all of a sudden or keep repeating a sentence while fading out are weird. They feel incomplete, and I end up feeling like I lost something in the course of the song. All of a sudden, boom, the song is gone. This is something that you should consider when writing a text as well. Your readers should feel the piece they are reading has closure and that you took them there.
Some good ways to close up an article are to wrap the content up, recap the key parts of your text, signal there will be a next one in case it’s a series, and maybe invite the readers to add their input on the subject in the comments section if there is one.
It’s good to add a references section at the end as well. It could include the ones you followed when writing the text, further information about the things you didn’t dig deeper in your text, and more content on the subject you spoke about to give it credibility. It can even include other articles that go in different directions from yours. Keep your reader interested in the subject.
Review process
Well, you got there! You wrote it! Time to publish, right? Nope! Self-reviewing and asking others to review your text are as important as writing. When we are in the "flow" we might miss many things, especially when we change the idea about a sentence and end up skipping or adding extra words, or making typos (those darn typos!).
Use the self-review moment to re-read your text with attention, slowly, as if you were reading it for the first time, and ask someone else to do the same, as if it was a smaller version of your audience. That will help you catch mistakes or blind spots in your text before they hit a larger audience, and don’t forget to use a spelling check tool (as advised before). After that, you will be more confident that you produced a nice-to-read text, and your readers will feel pleased to read it.
Wrap up
Ok, I might have broken my own rule of not writing texts that are too long… well, sheet happens. Anyway, I want to reiterate that by no means do I want to dictate how someone should write a technical text. All those tips are based on my experience while writing and reviewing many articles, and they are also not exhaustive. I’m sure there is a lot more, which you should feel free to mention in the comments if you know some more tips!
As the most important take of this article, remember: the goal of your text is to communicate accurately to someone else, so pay great attention to that.
References and further reading
- Technical Writing One
- Technical Writing Two
- Your Writing Shouldn’t Make Your Reader Feel Stupid
- Against ‘foo’ (and ‘bar’ too)
We want to work with you. Check out our "What We Do" section!
