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

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

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

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

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

Инструменти

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

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

Макроси

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

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

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

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

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

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

Шаблони

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Тагове

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

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

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

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

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

Доклади

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

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

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

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

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

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

Краен процес

Инструкция

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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