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