Как команда по документации исправила нужные страницы, задав вопрос на самой странице

У open-source проекта хорошая документация и реальная проблема: руководство по установке содержит небольшую неточность. Один из шагов изменился два релиза назад, и теперь новички застревают на одном и том же месте. Люди замечают это — в социальных сетях появляются недовольства, а в чате сообщества — пара растерянных вопросов, но мейнтейнеры не могут ничего с этим поделать, потому что ни в одной из жалоб не указано, **на какой странице** проблема. «Ваша документация устарела» — это эмоция, а не баг-репорт. Поэтому неверный шаг остается там месяцами, тихо отпугивая каждого нового пользователя, который пытается начать работу. Документация живет или умирает благодаря этому циклу: читатель натыкается на запутанный или неверный отрывок, сообщает мейнтейнерам, где именно он находится, и мейнтейнеры это исправляют. Уберите «где именно», и весь цикл остановится. ## Проблема: обратная связь без указания места — это шум Читатели готовы помочь. Они с радостью скажут вам, что страница непонятна. Чего они не станут делать, так это заниматься археологией, необходимой для того, чтобы эта помощь стала практически полезной: копировать URL, искать правильный канал для связи, описывать проблему и указывать, в каком разделе и в какой версии она найдена. Это слишком много шагов для того, кто пытается изучить ваш инструмент, а не проводить аудит вашей документации. В результате обратная связь, которая все же поступает, лишена единственного, что делает ее полезной: местоположения. У мейнтейнера, читающего «документация по API неверна», есть сотни страниц и ни малейшего понятия, где искать. GitHub issue помогает, но требует от случайного читателя наличия аккаунта, понимания вашего шаблона issue и полного переключения контекста с документации на что-то другое. Это трение отсеивает большую часть мимолетных отзывов, которые как раз и помогают выявлять мелкие ошибки, имеющие серьезные последствия. Результатом становится странный дисбаланс: множество читателей замечают проблемы, но почти ни об одной из них не сообщается в том виде, в котором вы могли бы ее исправить. ## Решение: ссылка «Сообщить о проблеме» на каждой странице Поместите небольшую ссылку **Сообщить о проблеме на этой странице** в футер каждой страницы документации. Это ссылка `mailto:`, и ее хитрость в том, что она автоматически подставляет путь к текущей странице в тему и тело письма. Читатель кликает, открывается его почтовый клиент с уже зафиксированным местоположением, и все, что ему остается добавить, — это описание того, что было не так. Поскольку документация обычно создается на основе шаблона или генератора статических сайтов, вы можете вставлять путь автоматически. На сайте с шаблонизатором добавьте переменную страницы прямо в ссылку: ```html <a href="mailto:docs@yourproject.dev?subject=Docs issue: {{page.path}}&body=Page: {{page.path}}%0A%0AWhat is wrong or confusing:%0AWhat would make it clearer:"> Сообщить о проблеме на этой странице </a> ``` Или настройте ее с помощью небольшой строки скрипта, чтобы она работала на любой странице без использования шаблонизатора: ```html <a id="docs-issue" href="#">Сообщить о проблеме на этой странице</a> <script> const a = document.getElementById('docs-issue'); const path = location.pathname; const body = 'Page: ' + path + '\n\nWhat is wrong or confusing:\nWhat would make it clearer:'; a.href = 'mailto:docs@yourproject.dev' + '?subject=' + encodeURIComponent('Docs issue: ' + path) + '&body=' + encodeURIComponent(body); </script> ``` Генератор на этом сайте создает закодированную ссылку; скрипт только подставляет актуальный путь. Теперь в теме каждого отчета указывается точная страница, и мейнтейнер может перейти прямо к исходному файлу. ## Почему для этого метод на странице превосходит баг-трекер Баг-трекер — это правильное место для исправления ошибок, но плохая «входная дверь» для обратной связи. Он требует наличия аккаунта, переключения контекста и знакомства с вашим процессом — барьеров, которые отпугивают случайного читателя, только что заметившего опечатку в примере кода. Ссылка `mailto:` встречает читателей именно там, где возникает путаница: на странице, в один клик, без аккаунта. Она захватывает длинный хвост мелких исправлений, которые никогда не добрались бы до трекера. Оба этих инструмента отлично работают вместе. Отчеты приходят по электронной почте с заранее проставленными тегами страницы; мейнтейнер сортирует их и открывает issue в трекере только для тех, которые стоит отслеживать. Вы получаете низкий уровень трения электронной почты на входе и строгость трекера на выходе. ## Настройка 1. Выберите почтовый ящик для документации, например `docs@`, за которым следят мейнтейнеры. 2. В генераторе укажите получателя, тему «Docs issue: [путь к странице]» и тело письма, которое запрашивает, что не так и что могло бы помочь. 3. Добавьте ссылку в футер шаблона вашей страницы, внедряя путь с помощью переменной страницы вашего генератора или небольшого скрипта выше. 4. Настройте маршрутизацию входящей почты по тегу темы «Docs issue:», чтобы отчеты попадали в одно место. 5. Замкните цикл: когда вы исправляете страницу, о которой сообщили, ответ читателю в одну строку превращает баг-репорт в лояльность. ## Что это экономит Первая экономия — это **время мейнтейнера, затрачиваемое на поиск проблем**. Когда в каждом отчете указана страница, вы пропускаете детективную работу и переходите сразу к исправлению. Отчет, который раньше был неинформативным «где-то что-то не так», превращается в двухминутное редактирование. Вторая — это **меньшее количество застрявших пользователей**. Ошибки в документации накапливаются: неверный шаг установки дает сбой не один раз, он подводит каждого новичка до тех пор, пока кто-нибудь это не исправит. Сокращение времени от «читатель заметил» до «мейнтейнер точно знает где» означает, что каждый плохой отрывок оттолкнет гораздо меньше людей. Для инструмента, который растет за счет внедрения, разблокировка новичков — это рост. Третья — это **объем и честность обратной связи**. Поскольку сообщение об ошибке требует всего одного клика и не требует наличия аккаунта, больше читателей делают это, включая тех, кто никогда бы не открыл issue в трекере. Вы узнаете о мелких, досадных ошибках, которые подрывают доверие, и узнаете о них, пока они еще имеют значение. ## Как сделать еще лучше - Автоматически заполняйте **версию документации или коммит** вместе с путем, чтобы вы могли определить, предшествовал ли отчет недавнему переписыванию. - Добавьте ссылку на **страницы 404** в вашей документации, где отсутствие страницы само по себе является полезным сигналом. - Оставьте адрес **зашифрованным (обфусцированным)**, чтобы боты не могли собрать его с тысяч публичных страниц. - Предложите видимую альтернативу для читателей без почтового приложения по умолчанию, например обычный адрес или ссылку на трекер. ## Основные выводы - Обратная связь по документации без указания места — это шум; читатели редко проделывают работу по ее добавлению. - Ссылка `mailto:` «Сообщить о проблеме» на каждой странице автоматически заполняет точный путь, поэтому каждый отчет становится полезным для работы. - Электронная почта на странице улавливает случайные исправления, которые отсеивает трекер, а затем питает трекер для реальных исправлений. - Это экономит время мейнтейнеров, быстрее разблокирует новичков и выявляет мелкие ошибки, которые незаметно снижают доверие. Создайте свою собственную ссылку для отзывов о документации в [генераторе](/#generator) или скопируйте настройку ниже.