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