Документацията за софтуера е просто набор от статии. Но дори и те могат да ви изкарат извън релси. Първо дълго търсите нужната инструкция. После се опитвате да разберете неразбираемия текст. Правите каквото е написано, а проблемът не се решава. Търсите друга статия, нервничите… След час се отказвате и заминавате. Така работи лошата документация. Какво я прави такава и как да я поправим - четете по-долу.
В нашата стара документация имаше много недостатъци. Вече почти година я преработваме, за да се уверим, че описаният по-горе сценарий не засяга нашите клиенти. Вижте, и .
Проблем 1. Непонятни, зле написани статии
Ако в документацията не може да се разбере нищо, какъв е смисълът от нея? Но никой не пише неразбираеми статии нарочно. Те възникват, когато авторът не мисли за аудиторията и целта, лее вода и не проверява текста за грешки.
- Аудитория. Преди да напишете статия, трябва да помислите за нивото на подготовка на читателя. Логично е, че в статия за начинаещи не бива да се пропуска основните стъпки и да се оставят технически термини без обяснения, а в статия за рядка функция, нужна само на професионалисти, да се обяснява значението на думата PHP.
- Цел. Още нещо, за което е добре да се помисли предварително. Авторът трябва да постави ясна цел, да определи полезното действие на статията, да реши какво ще направи читателят след нейното прочитане. Ако не се направи това, ще се получи описание, ради самото описание.
- Вода и грешки. Много излишна информация и канцеларизми, грешки и правописни грешки пречат на възприемането. Дори ако читателят не е грамар наци, небрежността в текста може да го отблъсне.
Обърнете внимание на съветите по-горе и статиите ще станат по-разбираеми - гарантирано. За да стане още по-добре, вземете на въоръжение нашите .
Проблем 2. Статиите не отговарят на всички въпроси
Лошо е, когато документацията не следва разработката, не отговаря на реални въпроси, грешките в нея не се коригират с години. Това са проблеми не толкова на автора, колкото на организацията на процесите вътре в компанията.
Документацията не следва разработката
Функцията вече е в релиз, маркетингът планира да я популяризира, но се оказва, че нова статия или превод все още няма в документацията. Поради това дори ни се е налагало да отлагаме релиза. Можем да молим всички да подават задачите на техническите писатели навреме, но това не работи. Ако процесът не бъде автоматизиран, ситуацията ще продължи да се повтаря.
Направихме промени в YouTrack. Задачата за написване на статия за новата функция попада при техническия писател в момента, в който започнат тестовете. Тогава маркетингът също научава за нея, за да може да се подготви за промоция. Уведомленията идват и в корпоративния мессенджър Mattermost, така че е невъзможно да пропуснете новини от разработчиците.
Документацията не отразява запитванията на потребителите
Ние сме свикнали да работим така: функцията излиза, ние я описваме. Посочваме как да я включите, изключите и направите фини настройки. Но какво, ако клиентът използва нашия софтуер по начин, който не сме предвидили? Или ако възникнат грешки, за които не сме помислили?
За да бъде документацията максимално пълна, препоръчваме да анализирате запитванията в поддръжка, въпросите в тематични форуми и търсенията в търсачките. Най-популярните теми да се предадат на техническите писатели, за да допълнят съществуващите статии или да напишат нови.
Документацията не се усъвършенства
Трудно е да направите всичко перфектно отначало, грешки винаги ще има. Можем да разчитаме на обратна връзка от клиентите, но едва ли те ще съобщават за всяка печатна грешка, неточност или неясна или непотърсена статия. Освен клиентите, документацията се чете и от служители, което означава, че те виждат същите грешки. Това може да се използва! Трябва само да създадем условия, при които е лесно да се съобщи за проблем.
Имаме група на вътрешния портал, където служителите оставят забележки, предложения и идеи за документацията. Нужна е статия на поддръжката, а я няма? Тестировчикът забеляза неточност? Партньор се оплака на мениджърите за развитие за грешки? Всичко в тази група! Техническите писатели веднага поправят нещо, прехвърлят нещо в YouTrack, взимат нещо за размисъл. За да не утихне темата, от време на време напомняме за съществуването на групата и важността на обратната връзка.
Проблем 3. Нужната статия трябва да се търси дълго
Статия, която не може да бъде намерена, не е по-добра от статия, която не съществува. Девизът на добрата документация трябва да бъде фразата „Лесно е да се търси, лесно е да се намери“. Как да постигнем това?
Подредете структурата и определете принципа на избор на теми. Структурата трябва да бъде максимално прозрачна, за да не се чудят читателите „Къде мога да намеря тази статия?“. Ако обобщим, има два подхода: от интерфейса и от задачите.
- От интерфейса. Съдържанието дублира разделите на панела. Така беше в старата документация на ISPsystem.
- От задачите. Заглавията на статии и раздели отразяват задачите на потребителите; в заглавията почти винаги има глаголи и отговори на въпроса „как да направя“. Сега преминаваме към такъв формат.
Какъвто и подход да изберете, уверете се, че темата отговаря на запитванията на потребителите и е представена така, че потребителят да реши конкретния си въпрос.
Настройте централизирано търсене. В идеалния свят търсенето трябва да работи дори когато направите печатна грешка или сбъркате с езика. Нашето търсене в Confluence все още не може да предложи това. Ако имате много продукти, а документацията е обща, адаптирайте търсенето към страницата, на която се намира потребителят. В нашия случай търсенето на главната страница работи за всички продукти, а ако вече сте в конкретния раздел, то само за статии в него.
Добавете съдържание и „хлебни трохи“. Добре е, когато на всяка страница има меню и хлебни трохи — пътя на потребителя до текущата страница с възможност да се върне на всеки ниво. В старата документация на ISPsystem трябваше да излезете от статията, за да стигнете до съдържанието. Беше неудобно, затова в новата поправихме това.
Поставете линкове в продукта. Ако хората нееднократно идват в поддръжката с един и същи въпрос, разумно е да добавите подсказка с решението на интерфейса. Ако имате данни или разбиране за момента, в който потребителят се сблъсква с проблема, можете също да го уведомите чрез имейл. И така се грижите, и облекчавате натоварването от поддръжката.
Отдясно в изскачащия прозорец е линк към статията за настройка на DNSSEC в секцията за управление на домейни на ISPmanager
Настройте кръстосани линкове в документацията. Статиите, които са свързани помежду си, трябва да бъдат «линкнати». Ако статиите представляват последователност, непременно добавете в края на всеки текст стрелки напред и назад.
Скоро човекът ще отиде да търси отговор на въпроса си не при вас, а в търсачката. Разочароващо е, ако там липсват линкове към документацията по технически причини. Така че се погрижете за оптимизация на търсенето.
Проблем 4. Устарялата структура затруднява възприемането
Освен лошите текстове, документацията може да бъде развалена и от дизайна. Хората са свикнали да четат добре оформени материали. Блогове, социални мрежи, медии — целият контент се подава не само красиво, но и удобно за четене, приятно за окото. Затова лесно можем да разберем болката на човек, който вижда текста както на скрийншота по-долу.
В тази статия има толкова много скрийншотове и акценти, че те не помагат, а само затрудняват възприемането (картината е кликаема)
Не трябва да правите от документацията лонгрид с куп ефекти, но основните правила трябва да се вземат предвид.
Структура. Определете ширината на основния текст, шрифта, размера, заглавията и отстъпите. Привлечете дизайнер, а за да приемете работата или да се справите сами, прочетете книгата на Артьом Горбунов «Типография и структура». В нея е представена само една от гледните точки за структурата, но тя е напълно достатъчна.
Акценти. Определете какво изисква акценти в текста. Обикновено това е пътят в интерфейса, бутоните, вставките на код, конфигурационните файлове, блоковете «Обърнете внимание». Задайте какви ще бъдат акцентите на тези елементи и ги фиксирайте в регламента. Имайте предвид, че колкото по-малко акценти, толкова по-добре. Когато има много, текстът «шумоли». Шум създават даже кавичките, ако се използват прекалено често.
Екранни снимки. Споразумейте се с екипа в кои случаи са нужни скрийншотове. Илюстрирането на всяка стъпка точно не е необходимо. Голямо количество скрийншотове, включително отделни бутони, затрудняват възприемането и развалят структурата. Определете размера, а също и формата на акцентите и заглавията на скрийншотовете и ги фиксирайте в регламента. Помнете, че илюстрациите винаги трябва да отговарят на написаното и да са актуални. Отново, ако продуктът редовно се обновява, проследяването на всичко ще бъде трудно.
Дължина на текста. Избягвайте прекалено дългите статии. Разделяйте ги на части, а ако не е възможно, добавяйте в началото на статията съдържание с якорни линкове. Простият начин да направите статията визуално по-кратка е да скриете техническите детайли, нужни на тесен кръг читатели, под спойлер.
Формати. Комбинирайте в статиите няколко формата: текст, видео и изображения. Това ще подобри възприемането.
Не се опитвайте да прикриете проблеми с красив дизайн. Честно, самите ние се надявахме, че "опаковката" ще спаси остарялата документация — не се получи. В текстовете имаше толкова визуален шум и ненужни подробности, че регламентът и новият дизайн бяха безсилни.
Много от описаното по-горе ще зависи от платформата, която използвате за документация. При нас, например, това е Confluence. И с него също се наложи да се поработи. Ако ви интересува, прочетете разказа на нашия уеб разработчик: .
С какво да започнете подобренията и как да оцелеете
Ако вашата документация е толкова обширна, колкото тази на ISPsystem, и не знаете от къде да започнете, започнете с най-сериозните проблеми. Клиентите не разбират документацията — погрижете се за подобряване на текстовете, направете регламенти, обучете писателите. Документацията е остаряла — вземете се за вътрешните процеси. Започнете с най-популярните статии за най-търсените продукти: попитайте поддръжка, вижте анализа на сайта и запитванията в търсачките.
Да кажем веднага — лесно няма да бъде. И бързо също едва ли ще стане. Освен ако не започвате и веднага правите всичко правилно. Едно знаем със сигурност — с времето ще стане по-добре. Но процесът няма да свърши никога :-).
Източник: habr.com
