Guides, glossaries, redpolitika. Where to begin?


Hello! I’m Alice, interface editor at SberMarket. My domain creates applications for couriers and admin panels for company employees. I have been working with texts of different formats for 8 years, 3 of which I have been in UX. I help businesses and users find a common language, I can explain “what is the strength” even to my grandmother.

Today I want to tell you how guides, glossaries and editorial policy will help to clean up the product and increase user loyalty.

What is what and why is it needed

Hyde is an instruction on one specific topic. To write it, you need to understand what problem we are solving now. For example, when I first joined the company, there were no rules on how we communicate with the audience: on “you” or “you”, seriously or in jokes, at a distance or as with best friends. The guide helped to make our communications seamless and comfortable for users.

Glossary – a collection of basic concepts within one topic or industry. We have a glossary of retailers, legal terms and stop words, a glossary with terms for each domain. They help us to properly decline proper nouns, achieve consistency in products, and even avoid lawsuits.

redpolicy is a global document for the entire company. All the rules for working with text are written there: from tone to commas. It makes your communications consistent, allows you to avoid common mistakes, and allows new employees to quickly join the work. As a result, tasks are solved faster, and corrections are reduced to a minimum.

When is it time to develop documentation

There are a number of signs:

But in short, as soon as you understand that the interface, text and design do not help the user.

I have a favorite example on this topic. Here it is ↓

Here are collected all the problems that I encountered at the beginning of working with the product.

The most important thing when working on UX texts is to consider perceptual patterns and context. Let’s take a closer look.

Patterns of perception. According to research Nielsen Norman Group, users don’t read text online. They “scan” it with their eyes diagonally, snatching out key words and phrases.

In the interface, the brain pays attention mainly to anchors: headings, pictures, buttons. And our task is to lay the main thing exactly there.

Context. This is an error screen. At the moment when our picker sees it, he stands in line at the checkout and checks if the payment for the order has come from the client. People ahead and behind him, noisy. He has a cart or a basket in his hands, which means that he holds the phone with one hand. The decision must be made quickly, in seconds.

Does the interface help him? It seems that he only increases the stress with exclamations, suggests repeating the mistake or leaving this scenario somewhere where there is also no solution.

I wrote three guides: rules for texts in the interface, typography and communication with users. If you rely on them, the output is a completely different screen.

Now it is less stressful, there is an explanation of what happened and where to go. And most importantly, it is clear in seconds, even if you do not read the small text. For users, this greatly simplifies interaction and increases brand loyalty, and also reduces the load on the call center and support chats. The company loses less money thanks to a few documents.

Where to begin

  1. Decide on an internal audience. Who exactly are you writing documentation for? Managers have their own terminology, their own way of perceiving information and their own place of storing this information; For designers it will be a little different. The service desk will have vocabulary that neither managers nor designers use.

  1. Analyze the experience of colleagues. There could have been a person in the company before you who had already started similar work and left the groundwork. Perhaps the product owner already has a vision in mind: ask how you can help the team so that the work is not wasted. In addition, it is useful to see what experts from other companies pay attention to, what items are in their documents, how large these documents are, where they are stored.

  1. Study the company’s products and highlight the problems. Since I have one application, I just install a test version and go through it from start to finish with all possible scenarios, making screenshots of errors. If you have several products, check out each of them, mark the most common problems.

  1. Choose the style and tone of the documentation. In this case, be sure to take into account the context. If you have a young team, a startup, you can fill the documentation with memes and slang – everyone will understand and even be delighted. If you work for a serious Forbes top company, you may need to hone your formal business style.

  1. Choose a platform. Learn where your audience is most likely to gather and search for information. Is it Confluence, Notion, cloud storage or some other knowledge base? Place the documentation where it will be convenient to use it.

What can go wrong

These mistakes are common for both novice and experienced editors.

To overdo or not to try

A document that does not cover a topic well is a disaster. But a global, detailed and “ideal” document is also a disaster if you just joined the company.

There is, for example, a very great temptation to engage in red politics at first, if it is not in the company. But this is a direct path to neurosis, because until you know the product enough, the document will constantly have to be redone: when you learn something new, when you get to know different departments, when you begin to understand the pains of users and business.

Set yourself a task for a trial period – how to immerse yourself in the product. In about three months you will have time to understand how he lives and what he relies on, get legacy.

Until then, you can practice writing guides. They are prepared in small portions, immediately coordinated and corrected. Later, from a series of guides and glossaries, you can assemble an excellent red policy, backing it all up with research.

Forget that work should be useful

Above, I advised you to look at the experience of colleagues; you just need to look, but not copy other people’s guides or red policy. First, it is unethical and fraught with consequences. Theft is easily identified, even if the document is closed. Secondly, it is useless: every company, every product has its own principles and its own voice. If we humanize, for example, Mango Insurance and VTB, these will be two different characters. Trying to transfer the cool principles of Mango to VTB will be like an owl and a globe trick that will not work well.

Another mistake in this direction is the lack of examples or irrelevant examples. I had to make the same changes over and over again, until a survey of colleagues showed that negative examples were also important. Now all the guides have descriptions of how to do it wrong and how to fix it – and they work!

The best thing to do is to take specific screenshots with errors and use them to show how to use the rules.

Don’t pay attention to styling

It is easy to get into a bureaucratic tone when working on red politics. After all, it seems that this is the only way this document will gain credibility and weight. But its primary goal is still to spread knowledge. If you use the language that you communicate on a daily basis, colleagues will be much more pleasant to learn from the experience. Yes, in a white-collar team it makes sense to use a more restrained tone, but even this does not justify the caterpillars of nouns in a round dance of adverbial phrases.

Careless design also makes it difficult to work with the document. Not only app users scan texts without reading. The task of the editor is to break the material into chapters, paragraphs and subparagraphs, make a table of contents, and insert links. That is, to make it as easy as possible to find information. Without it, your material will lie on the sidelines, no matter how useful it may be.

Make it once and for all, ignore feedback

When you do a lot of work, write guides and redact policy, you will want to put the documents in a frame and relax. But sooner or later something will change in a product or company, a new product will appear. And without edits, the documentation will simply become outdated and die.

It also happens quite often that the editor does not help employees to master the documentation and see the benefits in it, but simply dictates how to write. It’s repulsive. If you have created a knowledge base and silently placed it on a corporate resource, a very small part of the employees will go to study it. Not because people are lazy or bad. The same red policy is a tool, and it is important to teach others how to use it.

Documents will live on, and you, as the custodians of all this goodness, will need to take care of them, as if they were your indoor flowers. Water them, feed them and transplant them: update the terms and structure, supplement the materials, remind colleagues about them, and everything will be in order.

How to integrate this work into other processes

Take and install. There is no focus.

Writing documentation is the same task as writing text for a button or testing a flow. It’s just that in this case, the task is set not by the product, not by the designer or manager – you set it yourself. Accordingly, you are required to determine the scope of the task, stages and deadline, then add it to the calendar.

If you don’t make the time yourself, it will never come. As a beginner, for the first few weeks, I waited for the opportunity to sit down and work on the documentation for a few hours. Then I realized that I need to set more realistic requirements for myself. I began to write small pieces of work into the schedule – 20-40 minutes each, like meetings, in different parts of the day. Three months later, we had all the main documentation ready, including a large draft of the red policy, which is still functioning.

More about the results

I leave a checklist of arguments on how the creation of documentation and a unified knowledge base will help you:

The business is satisfied because its values ​​reach the audience, the processes are moving, there are no disputes in the team. And users understand the information, use the product with pleasure and come back. Such is the power of guides, glossaries and editorials.

Thanks for reading! I hope my experience was useful and now you will approach the creation of guides, glossaries and redactions without fear. And if you have any questions, I’ll be happy to answer them in the comments 🙂

The SberMarket tech team now has social networks with news and announcements. Follow us at Telegram and on YouTube, if you want to know what’s under the hood of a highly loaded e-commerce. And also we have podcast “For tech and these”. There, our EMs are trying to understand how cool IT companies have become those we love, and what we can learn from them.

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *