Дизайн в Confluence

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

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

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

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

Инструменти

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

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

макроси

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

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

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

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

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

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

Templates

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

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

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

Магия на масата

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

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

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

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

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

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

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

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

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

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

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

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

Например: имате таблица, която съдържа данните на всички служители – къде се намират географски и какви позиции заемат. За да изчислите колко хора има във всеки град, трябва да изберете в макроса "Pivot Table" реда, по който се агрегират данните (локация) и вида на операцията (добавяне).

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

Графики (платен плъгин)

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

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

Лесно агрегиране

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

Tags

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

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

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

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

Обърнете внимание на идентификатора - удобно е да го настроите да окачва различни групи имоти на различни страници (или дори различни групи имоти на една страница).

Отчети

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

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

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

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

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

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

Краен процес

Инструкция

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

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

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

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

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

Клопките

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

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

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

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

Ще дам пример за нашия процес на поддържане на информация за екипа.

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

Както можете да видите, имаме подробна таблица със свойства и веднага имаме инструкции как да поддържаме тази страница. Някои от етикетите се поставят от самите служители според инструкциите, в шаблона само основните: етикетът на картата карта на служител, маркер за посока посока-включвам и команден етикет екип-qa.

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

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

Заключение

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

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

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