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

Един open-source проект има добра документация и реален проблем: ръководството за инсталиране е леко погрешно. Една стъпка се е променила преди две версии и сега новодошлите засядат на едно и също място. Хората забелязват — има мърморения в социалните мрежи и няколко объркани въпроса в чата на общността — но поддържащите не могат да предприемат действия по нито едно от тях, защото нито едно от оплакванията не казва **коя страница**. „Вашата документация е остаряла“ е усещане, а не доклад за бъг. Така че грешната стъпка стои там с месеци, тихо отблъсквайки всеки нов потребител, който се опитва да започне. Документацията живее или умира от този цикъл: читателят попада на объркващ или грешен пасаж, казва на поддържащите точно къде, и поддържащите го поправят. Счупете „точно къде“ и целият цикъл спира. ## Проблемът: обратна връзка без местоположение е шум Читателите са готови да помогнат. Те с радост ще ви кажат, че дадена страница е объркваща. Това, което няма да направят, е археологията, необходима, за да направят тази помощ приложима — да копират URL адреса, да намерят правилния канал за контакт, да опишат проблема и да отбележат коя секция и коя версия. Това са твърде много стъпки за някой, който се опитва да научи вашия инструмент, а не да одитира документацията ви. Затова обратната връзка, която все пак пристига, е лишена от единственото нещо, което я прави полезна: местоположението. Един поддържащ, който чете „API документацията е грешна“, има стотици страници и никаква идея къде да търси. Един GitHub issue помага, но изисква от случайния читател да има акаунт, да разбере вашия шаблон за issue и да излезе изцяло от контекста на документацията — триене, което филтрира по-голямата част от мимолетната обратна връзка, която е точно обратната връзка, улавяща малки, но с голямо въздействие грешки. Резултатът е странен дисбаланс: много читатели забелязват проблеми, почти никой не бива докладван във форма, която можете да поправите. ## Решението: връзка „Докладвай за проблем“ на всяка страница Поставете малка връзка **Докладвай за проблем с тази страница** във футъра на всяка страница от документацията. Това е `mailto:` връзка, а нейният трик е, че предварително попълва текущия път до страницата в темата и тялото. Читателят кликва, имейлът му се отваря с вече заснетото местоположение и всичко, което добавя, е какво е било грешно. Тъй като документацията обикновено се изгражда от шаблон или генератор на статични сайтове, можете да инжектирате пътя автоматично. В сайт с шаблони, пуснете променливата за страницата директно във връзката: ```html <a href="mailto:[email protected]?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:[email protected]' + '?subject=' + encodeURIComponent('Docs issue: ' + path) + '&body=' + encodeURIComponent(body); </script> ``` Генераторът на този сайт създава кодираната връзка; скриптът само заменя активния път. Сега всеки доклад назовава точната страница в своята тема и поддържащият може да скочи направо към изходния файл. ## Защо на самата страница е по-добре от issue tracker за това Един issue tracker е правилното място за поправка, но лоша входна врата за обратна връзка. Той изисква акаунт, превключване на контекста и запознатост с вашия процес — бариери, които отблъскват случайния читател, който току-що е забелязал правописна грешка в пример за код. Връзката `mailto:` среща читателите там, където всъщност възниква объркването: на страницата, с едно кликване, без акаунт. Тя улавя дългата опашка от малки корекции, които никога не биха оцелели при пътуването до tracker. Двете работят добре заедно. Докладите пристигат по имейл, предварително маркирани със страницата; поддържащият ги сортира и отваря tracker issues само за тези, които си струва да бъдат проследени. Получавате ниското триене на имейла на входа и строгостта на tracker на изхода. ## Настройка 1. Изберете входяща кутия за документацията, като `docs@`, която поддържащите наблюдават. 2. В генератора задайте получателя, тема „Docs issue: [път до страницата]“ и тяло, което пита какво е грешно и какво би помогнало. 3. Добавете връзката към футъра на шаблона на вашата страница, като инжектирате пътя с променливата за страница на вашия генератор или малкия скрипт по-горе. 4. Насочвайте входящата поща по етикета на темата „Docs issue:“, така че докладите да попадат на едно място. 5. Затворете цикъла: когато поправите докладвана страница, отговор от един ред към читателя превръща доклада за бъг в добра воля. ## Какво спестява Първото спестяване е **времето на поддържащите, прекарано в локализиране на проблеми**. Когато всеки доклад назовава страницата, пропускате детективската работа и преминавате направо към поправката. Доклад, който преди е бил неприложимо „нещо някъде е грешно“, се превръща в двуминутна редакция. Второто е **по-малко блокирани потребители**. Грешките в документацията се натрупват: грешна стъпка при инсталиране не се проваля само веднъж, тя се проваля за всеки новодошъл, докато някой не я поправи. Съкращаването на времето от „читателят забелязва“ до „поддържащият знае точно къде“ означава, че всеки лош пасаж отблъсква много по-малко хора. За инструмент, който расте чрез приемане, отблокирането на новодошлите е растеж. Третото е **обем и честност на обратната връзка**. Тъй като докладването отнема едно кликване и не изисква акаунт, повече читатели го правят — включително тези, които никога не биха отворили tracker issue. Научавате за малките, срамни грешки, които подкопават доверието, и научавате за тях, докато все още имат значение. ## Направете го още по-добро - Автоматично попълвайте **версията на документацията или commit** заедно с пътя, за да можете да разберете дали даден доклад предхожда скорошно пренаписване. - Добавете връзката към **404 страници** във вашата документация, където липсваща страница сама по себе си е полезен сигнал. - Дръжте адреса **прикрит**, така че ботовете да не го събират от хиляди публични страници. - Предложете видим резервен вариант за читатели без приложение за електронна поща по подразбиране, като например обикновен адрес или връзка към tracker. ## Ключови изводи - Обратната връзка за документацията без местоположение е шум; читателите рядко си правят труда да прикрепят такова. - `mailto:` връзка „Докладвай за проблем“ на всяка страница предварително попълва точния път, така че всеки доклад да е приложим. - Имейлът на самата страница улавя случайните корекции, които един tracker филтрира, след което захранва tracker-а за реални поправки. - Спестява време на поддържащите, отблокира новодошлите по-бързо и извежда на повърхността малките грешки, които тихо струват доверие. Създайте своя собствена връзка за обратна връзка за документацията в [генератора](/#generator) или копирайте настройката по-долу.