Проектиране в Confluence

Здравейте на всички!

Аз се казвам Маша, работя като инженер по осигуряване на качество в групата на Тинькофф. Работата на QA предполагава много комуникации с различни хора от различни екипи, а аз освен това бях мениджър и лектор по образователни програми, така че моята комуникационна карта беше възможно най-широка. И в някакъв момент избухнах: осъзнах, че вече не мога, не мога, не мога да попълвам адски тонове нечетими таблици и документи.

Сигурен съм, че всеки от вас си представи в този момент това, за което говоря, и се поти ледено: списъци с фамилии без азбучен ред, таблици с hundreds of колони с объркано оформяне, таблици с хиляди редове, в които трябва да плъзгате пръста си по колелцето на мишката, за да видите заглавието, тонове страници с неномерувани инструкции, стотици имейли, пренасочвани помежду си с данни, които трябва да бъдат анализирани и систематизирани и натъпкани в също толкова нечетими таблици.

И ето, когато се успокоих малко, реших да напиша тази статия. Ще разкажа как може да се води нормална (дори понякога удобна) разнообразна ненужна документация. Надявам се, че статията ще се разпространи в мрежата и нивото на адските условия в съседните на разработката отдели поне малко ще спадне, а хората (и аз включително) ще станат малко по-щастливи.

Инструменти

Продуктовата документация обикновено се съхранява близо до кода, което е добре. А непродуктовата документация обикновено се съхранява на всякакви места. Често хората се опитват да прехвърлят информация от различни места в Confluence, и ние не сме изключение. Така че целият следващ разказ ще бъде за него.

Всъщност Confluence е усъвършенстван wiki-движок. Той позволява работа с данни под различни форми на представяне: текст с форматиране, таблици, разнообразни диаграми. Това е много интересен и мощен инструмент, но ако не знаете как да го подготвите, ще получите поредната купчина нечетими документи. Аз ще ви науча да го подготвяте!

Макроси

Почти всичката магия на Confluence се изгражда около макроси. Има много макроси и те могат да се комбинират помежду си. Те са платени и безплатни, по-долу ще бъдат различни примери за макроси със връзки към документацията за тях.

Интерфейсът за работа с макроси е максимално прост. За да добавите макрос, трябва да натиснете плюс и да изберете необходимия елемент от списъка.

Ако макросът е самодостатъчен, т.е. не изисква поставяне на нещо друго в него, - той изглежда като блок.

Ако за работата на макроса е необходимо нещо да се постави в него, той изглежда като рамка.

В една рамка можете да поставите неограничен брой други рамки, стига вашата пирамида да има логика.

Всеки макрос разполага с предварителен преглед: в него веднага се вижда дали правилно сте попълнили и настроили макроса.

Шаблони

В допълнение към макросите има удобен инструмент за предварително попълване на съдържание - шаблон.
Шаблоните могат да се използват при създаването на всяка страница: просто натиснете три точки до бутона 'Създай' и изберете нужния шаблон.

Тогава в създадената страница ще се добави всичкото съдържание, което има в шаблона.

Който и да е може да създава страници от шаблони, но само тези, които имат права, могат да създават или редактират самите шаблони. В шаблона може да се добавят допълнителни инструкции за това как да се води страницата.

Магията на таблиците

Всъщност, като технар, аз нежно обичам таблиците и мога почти всяка информация да я завия в тях (макар и не винаги ефективно). Самите таблици са ясни, структурирани, мащабируеми, магически!

Но дори и такава чудесна същност като таблицата може да бъде развалена. Възможно е да се използва успешно и дори да се подобри. За това по-долу.

Филтриране (платен плъгин)

Всяка огромна нечитаема таблица може да стане малко по-малка и малко по-четима с помощта на филтриране. За целта можете да използвате платения макрос «Филтър на таблиците».

В тази макрос трябва да се постави таблицата (може дори и най-грозната, важното е да я поставите цялата). В макроса можете да изберете колони за филтриране от падащо меню, текстови филтър, числов и филтър по дати.

Представете си, че цялата информация за кандидатите за всички позиции се записва в табличен списък. Разбира се, не сортиран - хората идват на интервюта не по азбучен ред. А вие трябва да разберете дали сте провели интервю с конкретен кандидат преди. Трябва просто да поставите този хаос в макрос за филтриране, да добавите текстов филтър по фамилия - и вуаля, информацията е на екрана.

Важно отметить, че филтрирането на огромни таблици може да влияе на работата на системата и времето за зареждане на страниците, затова е по-добре да не се налага на хората да създават огромни нечетими таблици (пример за процеса ще има в края на статията).

Сортиране (платен плъгин)

С помощта на магическия макрос «Филтър на таблиците» също така можете да зададете сортиране по подразбиране за всяка колона и да номерирате редовете. Или да щракнете върху всяка колона в таблицата, поместена в макроса за филтър, и сортиране по тази колона ще се извърши.

Например, ако имате същата таблица с кандидати и трябва да прецените колко интервюта са проведени в определен месец, сортирайте по дата и се радвайте.

Сводни таблици (платен плъгин)

Сега преминаваме към по-интригуващ случай. Представете си, че таблицата ви е огромна и трябва да изчислите нещо за нея. Разбира се, можете да я копирате в Excel, да извършите необходимите изчисления и след това да експортирате данните обратно в Confluence. Но можете и веднъж да приложите макроса «Сводна таблица» и да получите същия резултат, само че и обновяем.

Например: имате таблица, в която са събрани данни за всички служители — къде се намират териториално и какви длъжности заемат. За да изчислите колко души има в всеки град, трябва да изберете в макроса «Сводна таблица» реда, по който се агрегира информацията (местоположение) и типа на операцията (събиране).

Разбира се, можете да групирате по няколко признака едновременно, всички възможности можете да видите в документацията.

Диаграми (платен плъгин)

Както вече казах, не всички обичат таблици толкова много, колкото аз. За съжаление, мениджърите в повечето случаи не ги обичат изобщо. Затова всички обичат ярки цветни диаграми.
Създателите на Confluence определено знаеха за това (сигурно и те имат началство, което обича отчети и диаграми, как иначе). Затова можете да се възползвате от магическия макрос «Диаграма от таблица». В този макрос трябва да поставите сводната таблица от предходната точка, и ето — вашите сиви скучни данни са красиво визуализирани.

Разбира се, и в този макрос има настройки. Връзка към документацията на всеки макрос можете да намерите в режим на редактиране на този макрос.

Леснота на агрегирацията

Информация от предишните точки вероятно не беше откритие за вас. Но сега със сигурност знаете как да използвате макроси, а аз мога да премина към по-интересната част на статията.

Марки

Неприемливо е, когато хората съхраняват информация в една неструктурирана статия или огромна таблица. Още по-лошо е, когато част от тази информация не само е нечетливо оформена, но и разпръсната из пространствата на Confluence. За щастие, има възможност да съберете разпръснатата информация на едно място. За целта трябва да използвате етикети (познати на всички от социалните мрежи тагове).

На всяка страница можете да добавите неограничен брой етикети. Ако кликнете на етикет, ще попаднете на страница за агрегация, където има връзки към всички материали с този етикет, както и с набор от свързани етикети. Свързаните етикети са тези, които често се срещат на една и съща страница.

Свойства на страниците

На страницата можете да добавите още един интересен макрос за структуриране на информацията — «Свойства на страниците». В него трябва да предоставите таблица от два стълба, където първият ще бъде ключ, а вторият — стойност на свойството. Освен това, макросът може да бъде скрит от страницата, така че да не пречи на четенето на съдържанието, но страницата все пак ще бъде маркирана с необходимите ключове.

Обърнете внимание на ID — удобно е да се зададе, за да свържете различни групи свойства с различни страници (или дори различни групи свойства на една страница).

Доклади

Със етикетите можете да събирате отчети. Например, макросът «Отчет за съдържанието» събира всички страници с определен набор от етикети.

Но по-интересният отчет е макросът «Отчет по свойства на страницата». Той също така събира всички страници с определен набор от етикети, но не просто извежда техния списък, а съставя таблица (хващате ли връзката с началото на статията?), в която колоните са ключовете на свойствата на страницата.

Получава се сводна таблица по информация от различни източници. Приятно е, че тя предлага удобни функции: адаптивен дизайн, сортиране по всяка колона. Също така, такава отчетна таблица може да бъде конфигурирана вътре в макроса.

При конфигуриране можете да премахнете от отчета определени колони, да зададете състояние по подразбиране или брой на показваните записи. Освен това, можете да зададете ID на свойството на страницата, за да виждате само необходимата информация.

Например, имате множество страници на служители, като всяка от тях притежава набор от свойства за човека: какво ниво е, къде се намира, кога се е присъединил към екипа и така нататък. Тези свойства са обозначени ID = employee_inf. И има втори набор от свойства на същата страница, в който е събрана информация за човека като част от екипа: каква роля изпълнява, в кой екип се намира и така нататък. Тези свойства са обозначени ID = team_inf. Тогава при сглобяване на отчета можете да извлечете информация само по един ID или веднага по два – както е удобно.

Прелестта на този подход е в това, че всеки може да сглоби информационна таблица, която не дублира нищо и ще се актуализира при обновяване на основната страница. Например: на тимлида не му е важно, кога е наел своите разработчици, но му е важно каква роля всеки от тях изпълнява в екипа. Тимлидът ще си изготви отчет по екипа. А на счетоводителя изобщо не му пука, кой каква роля изпълнява, но важни разпоредбите – той ще си изготви отчет по разпоредбите. При това източникът на информация няма да се дублира или прехвърля.

Итоговият процес

Инструкция

И така, можем да структурираме красиво и ефективно да агрегатираме информация в Confluence, използвайки пример с макроси. Но в идеален случай трябва да направим така, че новата информация веднага да е структурирана и да попада във всички вече използвани механизми за агрегация.

Тук на помощ идва комбинацията от макроси и шаблони. За да накарате хората да създават нови страници в необходимия формат, можете да използвате макроса „Създаване от шаблон“. Той добавя бутона на страницата, при натискането на който се създава нова страница от желаните от вас шаблони. По този начин заставяте хората веднага да работят в необходимия формат.

В шаблона, от който давате създаването на страница, трябва предварително да добавите етикети, макроса „Свойства на страницата“ и таблица с необходимите ви свойства. Препоръчвам също така да добавите инструкции за това, с какви стойности трябва да се попълва страницата, и стойностите на свойствата.

Тогава финалният процес ще изглежда така:

1. Създавате шаблон за информация от определен тип.
2. В този шаблон добавяте етикети и свойства на страницата в макроса.
3. На удобно избрано място създавате основна страница с бутон, при кликване на който се създава дъщерна страница от шаблон.
4. Пускайте на основната страница потребители, които потенциално ще генерират необходимата информация (по необходимия шаблон, натискайки бутона).
5. Събирате отчета си по свойствата на страницата чрез етикети, които сте указали в шаблона.
6. Радвате се: имате всяка необходима информация в удобен формат.

Подводни камъни

Като инженер по качество, смело мога да твърдя, че нищо идеално не съществува в света. Дори божествените таблици не са идеални. И в гореспоменатия процес има подводни камъни.

• Ако решите да промените имената или състава на свойствата на страницата, ще трябва да актуализирате всички вече създадени обекти, за да се коректно предадат данните в обобщения отчет. Това е тъжно, но от друга страна, ви кара да обмислите в детайли "архитектурата" на вашия набор информация, което е доста интересна задача.
• Ще трябва да напишете доста инструкции за това как да попълвате информационните таблици и да ползвате етикети. Но от друга страна, можете просто да изпратите на всички заинтересовани хора тази статия.

Пример за съхранение на непроизводствена документация

Чрез описания по-горе процес може да се организира съхранение на почти всяка информация. Прелестта на подхода е в това, че е универсален: когато потребителите свикнат с него, те спират да генерират безпорядък. Освен това, значителен (но не безплатен) плюс е възможността за събиране на разнообразна статистика в реално време и да се рисуват красиви диаграми на базата на нея.

Предоставям пример за нашия процес на водене на информация за екипа.

За всеки човек в екипа решихме да създадем карта на служителя. Съответно, имаме шаблон, по който всеки нов човек създава своята карта и води в нейя цялата лична информация.

Както виждате, имаме разширена таблица със свойства и веднага има инструкции за това как точно да се води тази страница. Част от етикетите се поставят сами от служителите по инструкциите, в шаблона са само основните: етикет на картата employee-card, етикет на направлението direction-involve и етикет на екипа team-qa.

В крайна сметка, след като всеки създаде своя карта, се получава цялостна таблица с информация за служителите. Тази информация може да бъде използвана на различни места. Ресурсните мениджъри могат да съставят общи таблици, а лидерите на екипите — екипни таблици, добавяйки в избора етикета на екипа.

Чрез етикетите могат да се видят различни обобщения, например за qa-upgrade-plan ще се визуализират всички задачи за развитие на QA. В същото време всеки човек в своята карта на служителя води важна история и свой план за развитие — създава вложена страница от шаблона на плановете за развитие.

Заключение

Водете всяка документация така, че да не се срамувате от нея и да не причинявате мъка на потребителите!

Много надявам се, че статията ще бъде полезна и в цялата документация по света ще настъпи ред.

Източник: habr.com