This website uses cookies. By using the website you agree with our use of cookies. Know more

Culture

Clear Communication - Writing clearly when documenting FARFETCH APIs

By José Pedro Aragão
José Pedro Aragão
Two things I love: 1. Making lists. 2. Reviewing lists.
Top Stories
1 - Clear Communication - Writing clearly when documenting FARFETCH APIs
View All Posts
Clear Communication - Writing clearly when documenting FARFETCH APIs
Introduction

The Technical Writing Team at Farfetch are responsible for tasks such as writing the reference documentation and the manuals for the Farfetch Platform APIs. This blog post focuses on something that is very relevant for those tasks: clear communication.

What do we mean by clear communication?

Let's think of clear written communication as a text in which a reader who knows the meaning of all the individual words will also understand the intended meaning of the text, preferably in one fairly effortless reading.

"Clear communication" is therefore an objective that you want to achieve when you communicate -  to be clear.

The objective might seem like common sense. Surely, every person who communicates wants to be clear and wants to be understood. Even so, misunderstandings are always a possibility - misinterpreted words, misread sentences, wrong conclusions.

This might be a minor problem for some forms of communication. But, when we enter the world of technical writing, minor communication problems can provoke major problems.

So what do we do when we consciously make an effort to communicate in the most effective way?

We anticipate the ways in which something might not be understood. We eliminate sentences and words that might mislead or confuse the reader. We emphasize the main points of our message. We guarantee that we are guiding the reader to the desired conclusion.

Before we continue, let me make it clear that our work focuses on written communication. This means that, whenever I say communication, please assume it's written communication. Even if what I say might also apply to spoken communication, it's not guaranteed.

Why is clear communication important?



One way to define communication is 'the transmission of thoughts, information, ideas, and messages between people or groups'. But, unless the transmission is understood, communication has failed. When you make an effort to be clear, you are in fact fighting for effective communication.

Let's take a look at two ways of failing to communicate.

You write something confusing:

  • The meaning is contained in the text, but it's not properly explained.
  • The reader will be puzzled and frustrated by the text.
  • Even if the reader understands the meaning of the text after rereading, the reader will get distracted and be unhappy with you.

You write something ambiguous:

  • The meaning is not distinctly and sufficiently contained in the text, so it might be interpreted in more than one way.
  • The reader might misinterpret the text and initiate the wrong course of action.
  • The mistake could mean lost hours of work, money, and even lives.

As I said, misunderstandings can be minor. Let's suppose you are at a restaurant and, after reading the description on the menu, you order a new cocktail. The cocktail arrives, but it is not what you expected. You might complain to the waiter, or you might drink the cocktail, but it's not a serious problem.

Now, let's imagine that you are driving across the desert. Your car breaks down and you need to examine the engine. As you are not an expert mechanic, you consult the car manual. If the instructions are not clear, you are likely in trouble. This is not a common scenario, but it's easy to understand that there are situations where you truly want to avoid misunderstandings.

When and where is clear communication important?

As we've seen, when communication fails, the consequences can be serious.

This obviously doesn't mean every email and chat message needs several revisions. But what if you're writing a document that will serve as the main reference for a specific matter to a diverse audience? In this situation, you need to guarantee that every piece of information you want to communicate is clearly explained.

The concern with clear communication is particularly important when your audience contains people that:

  • are not native speakers of the language that is used
  • have different levels of understanding of the subject matter of the text
  • are highly dependent on your text to do their job correctly
  • might not be able to get in touch with you if they have doubts

How can we achieve clear communication?


So, we've been talking about clear communication, why should we care about it and when is it really relevant. Let's talk about how to achieve it.

We have to start by accepting that it's not possible to completely control who will be the reader and what the reader will do with a text. Therefore, we need to write in a way that limits the interpretation choices of the reader and reduces the opportunities for misunderstanding.

There are innumerable tactics to improve the clarity of a text. I will mention some of the tactics that the Technical Writing Team considers most important.

Note: some tactics below are specific to the English language.

Be careful when replacing words with pronouns

Pronouns such as 'this', 'these', 'it', 'its', 'which', or 'who' can sometimes hide the true meaning of a sentence. To add clarity to a text, it's often best to repeat nouns than to use pronouns to point at the nouns.

For example:

  • The process validated the address of the customer, which will need to be updated. ['which' refers to the address or the customer?]
  • The process validated the address of the customer. The address will need to be updated. [We repeated 'address', so now it's completely clear what needs to be updated.]

Another example:

  • The site presents a page with information about the product. It needs to be reviewed by the content manager. ['it' refers to the page, the information or the product?]
  • The site presents a page with information about the product. The information needs to be reviewed by the content manager. [We repeated 'information', so now it's completely clear what needs to be reviewed.]

Don't focus solely on length

There are tests that attempt to measure the readability of texts. The Flesch–Kincaid test, for example, uses metrics such as words-per-sentence and syllables-per-word.

Most tests of this kind consider that texts with shorter words and sentences are easier to read. But mathematical formulas do not understand grammar, context or meaning. So, while these tests might be useful tools, they should not be used to set a hard rule.

Less is not always more. Depending on your audience, sometimes you do need longer words and longer sentences to communicate with success.

For example:

  • I reviewed the documentation of the packaging procedure, which was updated recently. Its description will be added later, after an existing bug is fixed.
  • I reviewed the documentation of the packaging procedure, because the packaging procedure was updated recently. The description of the documentation will be added later, after the Development Team resolves an existing defect. [This version of the text would be considered more complex by a Flesch–Kincaid test. Nevertheless, this version is more clear and less ambiguous than the previous version.]

Sometimes, it's best to keep optional words

The English language has some support words that are optional and that people usually choose (consciously or unconsciously) not to use. Two of those words are 'that' and 'to'.

Removing support words from a text produces a shorter text. As discussed in the previous topic, a shorter sentence doesn't always mean a more effective sentence. Certain optional words in English make the logic of a sentence clearer.

For example:

  • When the procedure creates the product, the service is ready to validate the total price and process the list. [Validate and process seem to be part of the same step and happen at the same time. This might not be correct.]
  • When the procedure creates the product, the service is ready to validate the total price and to process the list. [We added a 'to', to separate more clearly the action validate from the action process.]

Another example:

  • The procedure decides the product needs to be updated. [Some readers will need to read the sentence twice, as it seems to be saying that the procedure is making a decision on the products.]
  • The procedure decides that the product needs to be updated. [We added a 'that', to avoid misleading the reader.]

Search for alternatives to words with too many meanings

Ordinary, familiar words sometimes have too many context-dependent meanings. For example, common words such as 'make', 'set', 'fix', or 'hold' might seem safe to use, but each one has multiple possible interpretations. Most readers will have less doubts if you use alternative words.

Some examples:

  • 'make' can be replaced by 'construct'
  • 'set' can be replaced by 'define'
  • 'fix' can be replaced by 'repair'
  • 'hold' can be replaced by 'conclude'

When you search for alternative words that have fewer meanings, make sure you do not pick very uncommon words.

Avoid more complex verb forms such as the passive voice

Sentences using the passive voice can confuse readers because the object of the action of the sentence becomes the actor of the sentence. This can make the sentence difficult to understand.

For example:

  • The total price value is updated when the product is added to the shopping bag. [Added by who? Updated by who?]
  • When the customer adds the product to the shopping bag, the Farfetch platform updates the total price value. [This is more clear, as we removed the passive voice and included the actors of the actions.]

Be careful with verbs with two or three words in them

If the reader is not a native speaker of English, two-word and three-word verbs may be a source of unnecessary complexity. Alternatives are often available.

Some examples:

  • 'open up' can be replaced by 'expand'
  • 'carry on' can be replaced by 'continue'
  • 'look at' can be replaced by 'examine'
  • 'follow up' can be replaced by 'track'
  • 'take advantage of' can be replaced by 'exploit'

Avoid nominalization

Nominalization is when you convert a verb such as 'decide' into an expression such as 'reach a decision with respect to'. This is another situation where adding more words produces additional and unnecessary complexity.

Some examples:

  • 'reach a conclusion' can be replaced by 'conclude'
  • 'make a recommendation' can be replaced by 'recommend'
  • 'hold a meeting' can be replaced by 'meet'
  • 'give an answer to' can be replaced by 'answer'

Conclusion

The Farfetch APIs, documentation, and manuals are used by a very diverse group of people, from all around the world. Some people will be English-native speakers, others will only understand basic English. Some people might be expert programmers, others might be on their first job. Some people might be Farfetchers with access to the API developers, others might depend entirely on the documentation to do their job.

With such a diverse audience, unclear documentation will certainly lead to lost time. This is why technical documents must be unusually simple, unambiguous and literal. Clarity is not merely desired - it is required.

Let me end by saying that, even if this topic might seem a concern reserved to technical writing, the tactics discussed shouldn't be underestimated. Global companies such as Farfetch, that employ people with a great variety of nationalities, rely heavily on the English language for communication. As most people are not native speakers of English, the tactics presented could certainly be used outside of the context of technical writing to improve communication.

References

List of most relevant books, articles, sites consulted:

Related Articles