Усім прывітанне!
Мяне клічуць Маша, я працую інжынерам па забеспячэнні якасці ў групе кампаній Тинькофф. Праца QA мяркуе мноства камунікацый з рознымі людзьмі з розных каманд, а я да таго ж была мэнэджэрам і лектарам адукацыйных праграм, таму мая карта камунікацый была максімальна шырокай. І ў нейкі момант я ўзарвалася: я зразумела, што больш не магу, не магу, не магу запаўняць пекла тоны нечытэльных табліц і дакументаў.
Напэўна кожны з вас уявіў сабе зараз тое, пра што я кажу, і абліўся халодным потам: спісы прозвішчаў без алфавітнага парадку, табліцы ў сотні слупкоў са з'ехалай вёрсткай, табліцы ў тысячы радкоў, у якіх трэба сціраць свой палец аб колца мышы, каб паглядзець загаловак, тоны старонак непранумараваных інструкцый, сотні якія перасылаюцца адзін аднаму лістоў з дадзенымі, якія трэба прааналізаваць і сістэматызаваць і запхнуць у такія ж нечытэльныя табліцы.
І вось, калі я крыху астыла, я вырашыла напісаць гэты артыкул. Я раскажу пра тое, як можна нармальна (нават часам зручна) весці разнастайную непрадуктовую дакументацыю. Спадзяюся, што артыкул разляціцца па сетцы і ўзровень адышча ў суседніх з распрацоўкай аддзелах хоць крыху знізіцца, а людзі (і я ў тым ліку) стануць крыху шчаслівымі.
Інструменты
Прадуктовая дакументацыя часта захоўваецца побач з кодам, і гэта добра. А непрадуктовая дакументацыя звычайна захоўваецца абы-дзе. Часта людзі імкнуцца пераносіць інфармацыю з розных месцаў у Confluence, і мы не выключэнне. Так што ўсё далейшае апавяданне аб ім.
Наогул Confluence – гэта прасунуты вікі-рухавічок. Ён дазваляе працаваць з дадзенымі ў розных відах адлюстравання: тэкст з фарматаваннем, табліцы, разнастайныя дыяграмы. Гэта вельмі цікавая і магутная прылада, але калі не ўмець яго рыхтаваць, тыя вы атрымаеце чарговую звалку нечытэльных дакументаў. Я навучу вас гатаваць!
макрасы
Амаль уся магія Confluence будуецца на макрасах. Макросаў вельмі шмат, і іх можна камбінаваць сябар з сябрам. Яны бываюць платнымі і бясплатнымі, далей будуць розныя прыклады макрасаў са спасылкамі на дакументацыю для іх.
Інтэрфейс працы з макрасамі максімальна просты. Каб дадаць макрас, трэба націснуць на плюс і абраць патрэбны элемент са спісу.
Калі макрас самадастатковы, гэта значыць не патрабуе ўстаўкі чагосьці яшчэ ўсярэдзіне сябе, - ён выглядае як блок.
Калі для працы макраса трэба нешта змясціць унутр яго, ён выглядае як рамка.
Пры гэтым можна змяшчаць унутр адной рамкі колькі заўгодна іншых, абы ў вашай пірамідзе была логіка.
У кожнага макраса ёсць папярэдні прагляд: у ім адразу відаць, ці правільна вы запоўнілі і наладзілі макрас.
шаблоны
Акрамя макрасаў ёсць зручная прылада предзаполнения кантэнту - гэта шаблон.
Шаблоны можна выкарыстоўваць пры стварэнні любой старонкі: проста націснуць на тры кропкі побач з кнопкай «Стварыць» і абраць патрэбны шаблон.
Тады ў створаную старонку дадасца ўвесь кантэнт, які ёсць у шаблоне.
Ствараць старонкі з шаблонаў можа хто заўгодна, а вось ствараць або рэдагаваць самі шаблоны - толькі тыя, у каго ёсць на гэта правы. У шаблон можна дадаць дадатковыя інструкцыі аб тым, як трэба весці старонку.
Магія табліц
Наогул-то я, як тэхнар, далікатна кахаю табліцы і магу амаль любую інфармацыю ў іх загарнуць (хоць гэта і не заўсёды эфектыўна). Самі па сабе табліцы выразныя, структураваныя, якія маштабуюцца, чароўныя!
Але нават такую выдатную сутнасць, як табліца, можна сапсаваць. А можна ўдала выкарыстоўваць і нават палепшыць. Аб гэтым ніжэй.
Фільтраванне (платны плягін)
Любую велізарную нечытэльную табліцу можна зрабіць крыху менш велізарнай і крыху больш за чытанай з дапамогай фільтрацыі. Для гэтага можна выкарыстоўваць платны макрас .
Унутр гэтага макраса трэба засунуць табліцу (можна нават самую выродлівую, галоўнае - запхнуць яе цалкам). У макрасе можна абраць слупкі для фільтра з выпадальным спісам, тэкставага фільтра, лікавага і фільтра па дат.
Вось уявіце, што ўсю інфармацыю па кандыдатах на ўсе вакансіі запісваюць таблічным спісам. Натуральна, неадсартаваны - людзі ж прыходзяць на сумоўі не па алфавіце. А вам трэба зразумець, ці праводзілі вы сумоўе з пэўным суіскальнікам раней. Трэба проста засунуць гэтае пекла ў макрас фільтра, дадаць тэкставы фільтр па прозвішчы - і вуаля, інфармацыя ў вас на экране.
Варта адзначыць, што фільтраванне велізарных табліц можа ўплываць на працу сістэмы і час загрузкі старонак, таму засунуць велізарную табліцу ў фільтр - часавы мыліца, лепш выбудаваць працэс, у якім людзям не даводзіцца ствараць велізарныя нечытэльныя табліцы (прыклад працэсу будзе ў канцы артыкула).
Сартаванне (платны плягін)
З дапамогай чарадзейнага макраса таксама можна задаць сартаванне па змаўчанні па любым слупку і пранумараваць радкі. Або націснуць на любы слупок табліцы, засунутай у макрас фільтра, і адбудзецца сартаванне па гэтым слупку.
Напрыклад, у вас ёсць тая ж самая табліца з суіскальнікамі і трэба прыкінуць, колькі сумоўяў было праведзена ў пэўны месяц, - сартуйце па даце і радуйцеся.
Зводныя табліцы (платны плягін)
Цяпер пяройдзем да кейса цікавей. Уявіце, што ваша табліца вялізная і трэба нешта палічыць па ёй. Вядома, можна скапіяваць яе ў Excel, палічыць патрэбнае і выгрузіць дадзеныя назад у Confluence. А можна адзін раз ужыць макрас і атрымаць той жа вынік, толькі яшчэ і які абнаўляецца.
Напрыклад: у вас ёсць табліца, у якой сабраны дадзеныя ўсіх супрацоўнікаў - дзе яны тэрытарыяльна знаходзяцца і якія пасады займаюць. Каб палічыць, колькі чалавек знаходзіцца ў кожным горадзе, вам трэба абраць у макрасе «Зводная табліца» радок, па якім агрэгуюцца дадзеныя (месцазнаходжанне) і тып аперацыі (складанне).
Натуральна, групаваць можна па некалькіх прыкметах адразу, усе магчымасці можна паглядзець .
Дыяграмы (платны плягін)
Як я ўжо казала, не ўсе кахаюць табліцы так моцна, як я. Нажаль, мэнэджары ў большасці сваёй іх наогул не кахаюць. Затое вельмі любяць яркія каляровыя дыяграмы.
Стваральнікі Confluence аб гэтым, безумоўна, ведалі (напэўна ў іх таксама ёсць начальства, якое кахае справаздачы і дыяграмы, куды ж без яго). Таму можна скарыстацца чароўным макрасам . У гэты макрас трэба пакласці зводную табліцу з папярэдняга пункта, і вуаля - вашыя шэрыя сумныя дадзеныя прыгожа злучаны іх.
Натуральна, у гэтым макрасе таксама ёсць наладкі. Спасылку на дакументацыю да любога макраса можна знайсці ў рэжыме рэдагавання гэтага макраса.
Прастата агрэгацыі
Інфармацыя з папярэдніх пунктаў напэўна не была для вас адкрыццём. Але зараз вы сапраўды ўмееце карыстацца макрасамі, а я магу перайсці да цікавейшай часткі артыкула.
пазнакі
Дрэнна, калі людзі захоўваюць інфармацыю ў адным неструктураваны артыкуле або велізарнай табліцы. Яшчэ горш калі часткі гэтай інфармацыі не толькі нечытэльна аформленыя, але і раскіданыя па прасторах Confluence. Балазе ёсць магчымасць сабраць раскіданую інфармацыю ў адным месцы. Для гэтага трэба скарыстацца (знаёмымі ўсім па сацсетках тэгамі).
На любую старонку можна дадаць любую колькасць пазнак. Калі націснуць на пазнаку, вы патрапіце на старонку агрэгацыі, дзе ёсць спасылкі на ўсе матэрыялы з гэтай пазнакай, а таксама з наборам звязаных пазнак. Змяненні, пазнакі - гэта тыя, якія часта сустракаюцца на адной старонцы.
Уласцівасці старонак
На старонку можна дадаць яшчэ адзін цікавы макрас для структуравання інфармацыі. . Унутр яго трэба падаць табліцу з двух слупкоў, першы будзе з'яўляцца ключом, а другі - значэннем уласцівасці. Прычым макрас можна схаваць са старонкі, каб ён не перашкаджаў чытаць кантэнт, але пры гэтым старонка ўсё роўна будзе адзначана патрэбнымі ключамі.
Звярніце ўвагу на ID - яго зручна задаваць, каб наважваць розныя групы ўласцівасцяў на розныя старонкі (ці нават розныя групы ўласцівасцяў на адну старонку).
Справаздачы
Па метках можна збіраць справаздачы. Напрыклад, макрас збірае ўсе старонкі з пэўным наборам пазнак.
Але цікавейшая справаздача - гэта макрас . Ён таксама збірае ўсе старонкі з вызначаным наборам пазнак, але не проста выводзіць іх спіс, а складае табліцу (ўлоўліваеце сувязь з пачаткам артыкула?), у якой слупкі - гэта ключы ўласцівасцяў старонкі.
Атрымліваецца зводная табліца па інфармацыі з розных крыніц. Прыемна, што ў яе ёсць зручныя функцыі: адаптыўная вёрстка, сартаванне па любым слупку. Таксама такую справаздачную табліцу можна канфігураваць усярэдзіне макраса.
Пры канфігураванні можна прыбраць са справаздачы нейкія слупкі, задаць стан па змаўчанні або колькасць якія адлюстроўваюцца запісаў. А яшчэ можна задаць ID уласцівасці старонкі, каб бачыць толькі патрэбную інфармацыю.
Напрыклад, у вас ёсць мноства старонак супрацоўнікаў, у гэтых старонак ёсць набор уласцівасцяў пра чалавека: якога ён узроўня, дзе знаходзіцца, калі прыйшоў у каманду і гэтак далей. Гэта ўласцівасці адзначаны ID = employee_inf. І ёсць другі набор уласцівасцяў на гэтай жа старонцы, у якім сабрана інфармацыя аб чалавеку, як аб частцы каманды: якую ролю чалавек выконвае, у якой камандзе знаходзіцца і гэтак далей. Гэтыя ўласцівасці адзначаны ID = team_inf. Тады пры зборцы справаздачы вы можаце вывесці толькі інфармацыю па адным айдзішніку або адразу па двух - як зручней.
Хараство такога падыходу ў тым, што кожны можа сабраць патрэбную для сябе інфармацыйную табліцу, якая не будзе нічога дубліраваць і будзе абнаўляцца пры абнаўленні асноўнай старонкі. Напрыклад: тыміду не важна, калі яго распрацоўшчыкі ўладкаваліся на працу, але важна, якую ролю кожны з іх выконвае ў камандзе. Тымлід збярэ сабе справаздачу па камандзе. А бухгалтару наогул усё роўна, хто якую ролю выконвае, але важныя пасады - ён збярэ сабе справаздачу па пасадах. Пры гэтым крыніца інфармацыі не будзе дублявацца ці пераносіцца.
Выніковы працэс
Інструкцыя
Такім чынам, мы можам хораша структураваць і эфектыўна агрэгаваць інфармацыю ў Confluence на прыкладзе выкарыстання макрасаў. Але ў ідэале трэба зрабіць так, каб новая інфармацыя адразу была структураванай і трапляла ва ўсе механізмы агрэгацыі, якія ўжо выкарыстоўваюцца.
Тут на дапамогу прыйдзе звязак макрасаў і шаблонаў. Каб прымусіць людзей ствараць новыя старонкі ў патрэбным фармаце, можна выкарыстоўваць макрас "Стварыць з шаблону". Ён дадае на старонку кнопку, па націску на якую ствараецца новая старонка з патрэбнага вам шаблону. Такім чынам вы прымушаеце людзей адразу працаваць у патрэбным вам фармаце.
У шаблон, з якога вы даяце ствараць старонку, трэба загадзя дадаць пазнакі, макрас "Уласцівасці старонкі" і табліцу патрэбных вам уласцівасцяў. Таксама рэкамендую дадаць інструкцыі аб тым, якімі значэннямі варта напаўняць старонку, і значэнні ўласцівасцяў.
Тады выніковы працэс будзе выглядаць так:
- Вы ствараеце шаблон для інфармацыі вызначанага тыпу.
- У гэты шаблон дадаеце пазнакі і ўласцівасці старонкі ў макрасе.
- У любым зручным месцы ствараеце каранёвую старонку з кнопкай, па зграі на якую ствараецца даччыная старонка з шаблону.
- Пускае на каранёвую старонку карыстальнікаў, якія патэнцыйна будуць генераваць патрэбную інфармацыю (па патрэбным шаблоне, націскаючы на кнопку).
- Збіраеце сабе справаздачу па ўласцівасцях старонкі праз пазнакі, якія вы паказалі ў шаблоне.
- Цешыцеся: у вас ёсць уся патрэбная інфармацыя ў зручным фармаце.
Падводныя камяні
Як інжынер па якасці, я смела магу сцвярджаць, што нічога ідэальнага ў свеце няма. Нават боскія табліцу неідэальныя. І ў прыведзеным вышэй працэсе ёсць падводныя камяні.
- Калі вы вырашыце памяняць назвы або склад уласцівасцяў старонкі, вам прыйдзецца праапдэйціць усе ўжо створаныя аб'екты, каб іх дадзеныя карэктна падцягнуліся ў зводную справаздачу. Гэта сумна, але, з іншага боку, прымушае дэталёва прадумаць "архітэктуру" вашага набору інфармацыі, што з'яўляецца вельмі цікавай задачай.
- Вам давядзецца напісаць прыстойную колькасць інструкцый аб тым, як запаўняць інфармацыйныя табліцы і карыстацца тэгамі. Але, з іншага боку, вы можаце проста кінуць ва ўсіх патрэбных людзей гэтым артыкулам.
Прыклад захоўвання непрадуктовай дакументацыі
Праз апісаны вышэй працэс можна арганізаваць захоўванне амаль любой інфармацыі. Хараство падыходу ў тым, што ён універсальны: калі карыстачы да яго абвыкаюць, яны перастаюць генераваць бардак. Таксама вялікі (але не бясплатны) плюс - магчымасць збіраць на лёце разнастайную статыстыку і маляваць па ёй прыгожыя дыяграмы.
Прывяду прыклад нашага працэсу вядзення інфармацыі аб камандзе.
Для кожнага чалавека ў камандзе мы вырашылі стварыць картку супрацоўніка. Адпаведна, у нас ёсць шаблон, па якім кожны новы чалавек стварае сабе гэтую картку і вядзе ў ёй усю асабістую інфармацыю.
Як бачыце, у нас разгорнутая табліца ўласцівасцяў і адразу ёсць інструкцыі аб тым, як менавіта весткі дадзеную старонку. Частку тэгаў прастаўляюць самі супрацоўнікі па інструкцыях, у шаблоне толькі асноўныя: тэг карткі employee-card, тэг напрамкі direction-involve і тэг каманды team-qa.
У выніку, пасля таго як кожны стварыў сабе картку, атрымліваецца поўная табліца з інфармацыяй па супрацоўніках. Гэтую інфармацыю можна выкарыстоўваць у розных кропках. Рэсурсныя менеджэры могуць сабраць сабе агульныя табліцы, а ліды каманд - камандныя табліцы, дадаючы ў выбарку тэг каманды.
Па тэгах можна ўбачыць розныя зводкі, напрыклад па qa-upgrade-plan адлюструюцца ўсе заданні на развіццё QA. Пры гэтым кожны чалавек у сваёй картцы супрацоўніка вядзе важную гісторыю і свой план развіцця - стварае ўкладзеную старонку з шаблону планаў развіцця.
Заключэнне
Вядзіце любую дакументацыю так, каб за яе не было сорамна, а карыстальнікам не было пакутліва балюча!
Вельмі спадзяюся, што артыкул будзе карысны і ва ўсіх дакументацыях свету настане парадак.
Крыніца: habr.com