Софтверска документација је само скуп чланака. Али чак и они могу да вас излуде. Прво, дуго ћете тражити потребна упутства. Онда разумете нејасан текст. Радите како је написано, али проблем није решен. Тражиш други чланак, унервозиш се... Сат времена касније одустанеш од свега и одеш. Овако функционише лоша документација. Шта га чини оваквим и како то поправити - прочитајте испод реза.
У нашој старој документацији било је много недостатака. Прерађујемо га већ скоро годину дана тако да горе описани сценарио не утиче на наше клијенте. види, и .
Проблем 1: Нејасни, лоше написани чланци
Ако је документацију немогуће разумети, која је сврха тога? Али нико намерно не пише неразумљиве чланке. Оне се дешавају када аутор не размишља о публици и намени, сипа воду и не проверава текст да ли има грешака.
- Публика. Пре него што напишете чланак, морате размислити о нивоу припреме читаоца. Логично је да у чланку за почетника не треба прескочити основне кораке и оставити техничке термине без објашњења, већ у чланку о реткој особини која је потребна само професионалцима треба објаснити значење речи ПХП.
- Циљ. Још једна ствар о којој треба размислити унапред. Аутор мора да постави јасан циљ, утврди користан ефекат чланка и одлучи шта ће читалац урадити након што га прочита. Ако се то не уради, добићете опис ради описа.
- Вода и бубе. Много је непотребних информација и бирократије, грешке и штампарске грешке ометају перцепцију. Чак и ако читалац није нациста граматике, непажња у тексту га може одбити.
Узмите у обзир горе наведене савете и чланци ће постати јаснији - гарантовано. Да буде још боље, користите наше .
Проблем 2. Чланци не одговарају на сва питања
Лоше је када документација не иде у корак са развојем, не одговара на права питања, а грешке у њој се годинама не исправљају. То су проблеми не толико аутора, колико организације процеса у компанији.
Документација не иде у корак са развојем
Функција је већ објављена, маркетинг планира да је покрије, а онда се испоставља да нови чланак или превод још увек није у документацији. Чак смо морали да одложимо пуштање због овога. Можете тражити од свих да предају задатке техничким писцима на време колико год желите, али то неће успети. Ако процес није аутоматизован, ситуација ће се поновити.
Унели смо промене у ИоуТрацк. Задатак писања чланка о новој особини пада на техничког писца у истом тренутку када функција почиње да се тестира. Затим маркетинг учи о томе како би се припремио за промоцију. Обавештења такође долазе у Маттермост корпоративни гласник, тако да је једноставно немогуће пропустити вести од програмера.
Документација не одражава захтеве корисника
Навикли смо да радимо овако: појавила се функција, причали смо о томе. Описали смо како да га укључите, искључите и извршите фина подешавања. Али шта ако клијент користи наш софтвер на начин на који нисмо очекивали? Или има грешака о којима нисмо размишљали?
Да би документација била што комплетнија, препоручујемо да анализирате захтеве за подршку, питања на тематским форумима и упите у претраживачима. Најпопуларније теме биће пренете техничким писцима како би могли да допуне постојеће чланке или да напишу нове.
Документација се не унапређује
Тешко је то одмах урадити савршено; и даље ће бити грешака. Можете се надати повратним информацијама од купаца, али је мало вероватно да ће пријавити сваку грешку у куцању, нетачност, неразумљив или непронађен чланак. Осим клијената, документацију читају и запослени, што значи да виде исте грешке. Ово се може користити! Само треба да створите услове у којима ће бити лако пријавити проблем.
На интерном порталу имамо групу у којој запослени остављају коментаре, сугестије и идеје на документацију. Да ли је за подршку потребан чланак, али не постоји? Да ли је тестер приметио нетачност? Да ли се партнер жалио менаџерима развоја на грешке? Сви у овој групи! Технички писци поправљају неке ствари одмах, неке ствари преносе на ИоуТрацк, а другима дају времена за размишљање. Да тема не би замрла, с времена на време вас подсећамо на постојање групе и важност повратних информација.
Проблем 3. Потребно је много времена да се пронађе прави чланак.
Чланак који се не може наћи није ништа бољи од чланка који се не може наћи. Мото добре документације треба да буде „Лако претраживати, лако пронаћи“. Како то постићи?
Организовати структуру и одредити принцип избора тема. Структура треба да буде што је могуће транспарентнија да читалац не помисли: „Где могу да нађем овај чланак?“ Да резимирамо, постоје два приступа: од интерфејса и од задатака.
- Из интерфејса. Садржај дуплира одељке панела. То је био случај у старој документацији ИСПсистема.
- Од задатака. Наслови чланака и одељака одражавају задатке корисника; Наслови скоро увек садрже глаголе и одговоре на питање „како да“. Сада прелазимо на овај формат.
Који год приступ да одаберете, уверите се да је тема релевантна за оно што корисници траже и да је покривена на начин који се посебно односи на питање корисника.
Подесите централизовану претрагу. У идеалном свету, претрага би требало да функционише чак и када погрешно напишете или погрешите језик. Наша досадашња претрага у Цонфлуенцеу не може нас задовољити овим. Ако имате много производа и документација је општа, прилагодите претрагу страници на којој се корисник налази. У нашем случају, претрага на главној страници ради за све производе, а ако сте већ у одређеном одељку, онда само за чланке у њему.
Додајте садржај и презле. Добро је када свака страница има мени и крушне мрвице - пут корисника до тренутне странице са могућношћу повратка на било који ниво. У старој документацији ИСПсистема, морали сте да изађете из чланка да бисте дошли до садржаја. Било је незгодно, па смо га поправили у новом.
Поставите везе у производ. Ако људи изнова и изнова долазе у подршку са истим питањем, има смисла додати наговештај са његовим решењем у интерфејс. Ако имате податке или увид у то када корисник има проблем, можете га обавестити и мејлинг листом. Покажите им бригу и скините терет са подршке.
Десно у искачућем прозору је веза до чланка о подешавању ДНССЕЦ-а у одељку за управљање доменом ИСПманагер-а
Поставите унакрсне референце унутар документације. Чланци који су међусобно повезани треба да буду „повезани“. Ако су чланци узастопни, обавезно додајте стрелице напред и назад на крају сваког текста.
Највероватније ће особа прво отићи да тражи одговор на своје питање не вама, већ претраживачу. Штета ако тамо нема линкова ка документацији из техничких разлога. Зато водите рачуна о оптимизацији за претраживаче.
Проблем 4. Застарели изглед омета перцепцију
Поред лоших текстова, документацију може покварити дизајн. Људи су навикли да читају добро написане материјале. Блогови, друштвене мреже, медији - сав садржај је представљен не само лепо, већ и лако читљив и пријатан за око. Због тога можете лако разумети бол особе која види текст као на слици испод.
У овом чланку има толико снимака екрана и истакнутих делова да они не помажу, већ само ометају перцепцију (на слику се може кликнути)
Не би требало да правите лонгреад од документације са гомилом ефеката, али морате узети у обзир основна правила.
Лаиоут. Одредите ширину текста, фонт, величину, наслове и паддинг. Унајмите дизајнера, а да бисте прихватили посао или га урадили сами, прочитајте књигу Артјома Горбунова „Типографија и распоред“. Представља само један поглед на распоред, али је сасвим довољан.
Издвајања. Одредите шта је потребно нагласити у тексту. Обично је ово путања у интерфејсу, дугмад, уметци кода, конфигурациони фајлови, блокови „Молим вас, обратите пажњу“. Одредите колика ће бити расподела ових елемената и забележити их у правилнику. Имајте на уму да што мање пражњења, то боље. Када их има много, текст је бучан. Чак и наводници стварају буку ако се користе пречесто.
Снимке екрана. Договорите се са тимом у којим случајевима су потребни снимци екрана. Свакако нема потребе да се илуструје сваки корак. Велики број снимака екрана, укљ. одвојена дугмад, ометају перцепцију, покварите изглед. Одредите величину, као и формат истицања и потписа на снимцима екрана и запишите их у правилник. Запамтите да илустрације увек треба да одговарају ономе што је написано и да буду релевантне. Опет, ако се производ редовно ажурира, биће тешко пратити све.
Дужина текста. Избегавајте превише дугачке чланке. Раздвојите их на делове, а ако то није могуће, додајте садржај са сидреним линковима на почетак чланка. Једноставан начин да се чланак визуелно скрати је да се испод спојлера сакрију технички детаљи потребни уском кругу читалаца.
Форматс. Комбинујте неколико формата у својим чланцима: текст, видео и слике. Ово ће побољшати перцепцију.
Не покушавајте да прикријете проблеме лепим распоредом. Искрено, и сами смо се надали да ће „омотач“ спасити застарелу документацију - није успело. Текстови су садржавали толико визуелне буке и непотребних детаља да су прописи и нови дизајн били немоћни.
Већи део горе наведеног биће одређен платформом коју користите за документацију. На пример, имамо Цонфлуенце. Морао сам и ја да петљам са њим. Ако сте заинтересовани, прочитајте причу нашег веб програмера: .
Где почети да се побољшавамо и како преживети
Ако је ваша документација огромна као ИСПсистем и не знате одакле да почнете, почните са највећим проблемима. Клијенти не разумеју документ - побољшајте текстове, направите прописе, обучите писце. Документација је застарела - водите рачуна о интерним процесима. Почните са најпопуларнијим чланцима о најпопуларнијим производима: питајте подршку, погледајте аналитику сајта и упите у претраживачима.
Одмах да кажемо – неће бити лако. И мало је вероватно да ће функционисати брзо. Осим ако тек почињете и не урадите праву ствар одмах. Једна ствар коју сигурно знамо је да ће временом бити боље. Али процес се никада неће завршити :-).
Извор: ввв.хабр.цом