How can you, as a producer, write for the reader?

Clear language (tone of voice) is about taking a product’s personality and expressing it through the way you say things. If we imagine our product as a tool that enables us to have a conversation with our users, a carefully considered tone of voice can be decisive for how users experience the product.

Focusing on DX (developer experience), we want developers, product owners, and other platform users to acquire knowledge efficiently without having to read between the lines to understand what is being communicated.

Keep the target audience in mind when you write

Clear language means communication with such a clear wording, structure, and visual design that readers in the target group find the information they need, understand it, and can use it.

But who are the readers in the target group, exactly? In short, the readers of the developer portal consist of the developers who use the APIs and the project managers or product owners (APOs) who publish content concerning the APIs. By forming an impression of who the actual readers of the developer portal are, it becomes easier to express yourself in a way that makes it simpler for the recipients to understand:

Developers often have stressful days, but they possess a strong “can‑do” attitude to achieve their goals. The systems they work with need to be efficient so they can finish the tasks they are working on and move on to the next one. Therefore it is important that the developer portal provides them with the information they need in the most concise, to‑the‑point manner possible. Here, things do not need to be repeated multiple times or expanded more than necessary.

Even though developers’ calendars are packed, they do not let the stress take over. They are well liked by colleagues and aren’t afraid to add an emoji or two to express how they feel, or as a means to spright up the mood in a chat. Emojis are therefore warmly welcome in the developer portal (with some reasonable limits, of course). Read more about using emojis in documentation here.

Product owners have a lot of responsibility. They usually play the main role in planning, executing, monitoring, controlling, and closing projects. They are also responsible for documenting the APIs on the developer portal. With an editorial focus in mind, the documentation is written in a formal way that may not contain emojis to the same extent as a developer would produce the same content.

Since product owners have many things to keep track of, they prefer to write in a mature and universal language. As content‑producing product owners on the developer portal, you have a responsibility to remember that what is important to you as a writer is not always the most important thing for the reader.

Practical support for you as a content producer:

• Consider the audience who will read the content and what mindset they are in.
  Is this their first time hearing about the product, service, or company? Then the content should be a bit lighter, providing value for the target audience. If the content is already familiar to the audience, you can have “heavier and more converting” content.

• Provide a description of every abbreviation.
  Often it can save a lot of time to use abbreviations. But remember—many abbreviations are industry‑specific jargon used internally in companies and are not always widely known. Every time you introduce a new abbreviation, it is important to give the reader a description of what it means. Afterwards you can use the abbreviation as much as you like. If you wish, you can also give the reader an overview of all the abbreviations you use, as the documentation sharing has done here.

• Can what you write be understood more easily with an illustration?
  Mermaid lets you create diagrams and visualizations using text and code.

• Write simply.
  Is what you write understandable even if you cut out a word or a sentence? Cut it. Are you unsure whether you have explained enough? See if a colleague who is not familiar with your service can understand what you have written.

• Sharpen your language.
  Ask questions of your own text. What does it mean? What am I trying to convey here? Why am I writing this?

• Make clear why the reader should read and use the text.
  If the purpose of the text is for the reader to take action, make sure this is evident.

• Include what is relevant for the reader. Write briefly.
  This saves space, and the reader saves time. Think carefully about what should be included in the text. Can you remove text that the reader is unlikely to benefit from?

• Place the most important thing for the reader first or prominently in the text.
  What is most important to you as a writer is not always the most important for the recipient. Often it is wise to write a conclusion or a summary first.