Цели документации — решить проблему пользователя, кратко и исчерпывающе ответить на его вопросы, а также предупредить об ошибках и ограничениях системы. Голос и тон документации помогают достичь этих целей.
Пользовательская документация #
Голос пользовательской документации вежливый и сдержанный, но не формальный. Мы обращаемся к пользователю на «вы» и объясняем сложные вещи простым языком. Не используем канцеляризмы, сленг, профессиональный жаргон и сложные синтаксические конструкции.
Тон документации нейтральный и обучающий. Мы не влияем на восприятие и выбор пользователя и даём информацию без рекламных формулировок, эпитетов и оценочных суждений.
В документации не используются разговорные или эмоционально окрашенные слова и выражения. Они неуместны: обычно пользователь обращается к документации, если запутался в интерфейсе или столкнулся с проблемой. Он может нервничать или спешить.
| Слишком формально | Слишком разговорно | Правильно |
|---|---|---|
| В процессе получения заказа вы можете отказаться от товаров. Мы произведём возврат денежных средств. | Если вы решите, что товары вам больше не нужны, просто откажитесь от них в пункте выдачи! Мы с радостью вернём вам деньги. | При получении вы можете отказаться от ненужных товаров — мы вернём за них деньги. |
Мы не используем запреты и не грубим пользователю, а предупреждаем о возможных последствиях его действий и об ограничениях системы.
| ❌ | ✅ |
|---|---|
| Обязательно укажите причину, по которой отклоняете акт, иначе мы его не рассмотрим. | Если вы не укажете причину, по которой вы отклоняете акт, мы не сможем его рассмотреть. |
| Если вы будете часто возвращать товары, на которые оставляли отзывы за баллы, мы запретим вам участвовать в акции в течение 60 дней. В течение этого срока баллы за отзывы вы не получите. | Если вы часто возвращаете товары, на которые оставляли отзывы за баллы, Ozon может отстранить вас от участия в акции на 60 дней. В течение этого срока вы не сможете получать баллы за отзывы. |
Мы верим, что пользователь не нуждается в излишней опеке, поэтому даём только полезную информацию без избыточных деталей. Это помогает сделать инструкцию более краткой и простой.
| ❌ | ✅ |
|---|---|
| Откройте приложение Ozon и с помощью поиска найдите нужные товары. Чтобы добавить товар в корзину, нажмите Добавить в корзину. | Выберите товары и добавьте их в корзину. |
Документация для внутренних сервисов #
Голос и тон документации для внутренних сервисов зависят от целевой аудитории и её экспертизы. Обычно такую документацию читают пользователи, партнёры и сотрудники, которые знакомы с продуктом. В ней можно использовать технические термины и жаргон — это сделает документацию короче и понятнее для целевой аудитории.
| ❌ | ✅ |
|---|---|
| Можно опубликовать новую функциональность так, чтобы её увидели сначала 10%, потом 50% и 100% пользователей. | Можно раскатить фичу сначала на 10%, потом на 50% и на 100% пользователей. |
| Этот инструмент помогает легко и быстро перенаправлять пользователей из одного канала в другой. | Этот инструмент помогает легко и быстро переливать трафик между вариантами. |
Если предназначение документации — не пошаговая инструкция, а памятка или онбординг, к которым будут обращаться сотрудники внутри компании, в такой документации можно использовать более энергичный и разговорный голос и тон. Например, обращаться к читателю на «ты» и использовать эмодзи.
| ❌ | ✅ |
|---|---|
| Чтобы сотрудник эффективно прошёл стажировку, ознакомьтесь с этой памяткой. | Привет! 👋🏼 Чтобы стажировка новичка прошла эффективно, ознакомься с этой памяткой. |