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