Всім привіт!
Мене звуть Маша, я працюю інженером із забезпечення якості у групі компаній Тінькофф. Робота 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