Аудит технічної документації: кому, навіщо, як

Мене звати Ірина Ісай, я технічна письменниця, або техрайтерка, кіберспортивного медіахолдингу WePlay Esports. Хочу поділитися своїм досвідом аудиту технічної та підготовки продуктової документації одночасно для кількох продуктів компанії, де я працюю наразі. Ця історія охоплюватиме і досвід з моїх попередніх проєктів — там теж було багато цікавого та корисного.

Моя історія співпраці з WePlay Esports, частиною холдингу TECHIIA, почалася саме з такого завдання: провести аудит документації. За минулий рік я не раз чула від різних компаній про бажання зробити його. Одні хотіли найняти техрайтера на повний день, щоб провести аудит і після цього впроваджувати розроблені рекомендації, інші — лише проконсультуватися щодо процесу.

Тож запрошую менеджерів команд, техрайтерів, продакт-оунерів провести разом наступні 15 хвилин. Поговоримо про аудит технічної та продуктової документації: що це, навіщо та як краще його проводити. Тема свіжа й мало досліджена — її обговорюють у статтях і коментарях техрайтерської спільноти не надто жваво.

А ще запрошую до розмови команди розробників і тестувальників. Якщо вас бісять техрайтери, які постійно щось торочать про документацію, відривають від роботи, допитуються, де ваші нотатки, намагаються змусити вас щось десь задокументувати, можливо, тут ви знайдете відповіді на свої запитання або підказки, як налагодити співпрацю з ними.

Ілюстрація Аліни Самолюк

Наша розмова має на меті врівноважити дві життєві несправедливості:

Не існує правил чи стандартів, за якими має відбуватися аудит документації. Матеріалів на цю тему в мережі — мінімум. Не тому, що хтось ледачий чи жадібний на досвід і знання. Просто галузь ІТ загалом дуже мінлива: всі підходи та процеси змінюються з такою швидкістю, що не встигнеш закінчити інструкцію чи рекомендацію, як уже потрібно писати нову. Сподіваюся, мій досвід полегшить життя, а може, й надихне тих, хто збирається взятися за цю нелегку справу.
Команди й керівництво компаній не вважають аудит документації чимось украй необхідним, відкладають його до кращих часів. Багато хто взагалі не чув про нього. Навіть саме слово «аудит» сприймають негативно: це ж певна «перевірка» роботи, тож команди ставляться дещо вороже до такого втручання. Буде добре, якщо мої роздуми принаймні змінять ваше ставлення.

Аудит документації

Почнемо з визначення термінів.

Аудит продуктової та технічної документації — це комплексна перевірка наявної документації щодо актуальності, достовірності, повноти, відповідності визначеним стилям та іншим попередньо встановленим критеріям і вимогам. Мета експерта чи команди, що пірнає в такий аудит, — оцінити поточний стан справ, визначити, чого бракує, та надати необхідні для усунення недоліків рекомендації.

Аудит документації треба проводити з певною регулярністю. Необов’язково має бути прив’язка до періоду — можливо, раз на версію або під час зміни менеджменту, стратегії розвитку або перезавантаження команди. Багато чого залежить від інтенсивності розвитку продукту та визначених цілей аудиту. Зазвичай це завдання йде від топменеджмента і становить один з етапів аудиту всіх продуктів компанії. Але трапляється, що потребу в аудиті визначає й сам техрайтер або команда, з якою він працює, попередньо окресливши чіткі цілі.

Нерідко чую: «Навіщо витрачати стільки часу та грошей на документування? У нас і так усе працює».

Ось лише кілька причин.

Онбординг. Якщо притомної документації у вас немає, це може означати, що шматки експертизи та інформації про продукт тримаються у мізках окремих людей. Часу поділитися з новачками своїми знаннями у них часто немає.

Тож замість того, щоб змушувати новеньких бігати по офісу від столу до столу з купою запитань, краще мати структурований гайд, де буде докладна та актуальна інформація. По-перше, гайд зробить онбординг м’якшим: новенькі швидше схоплять інформацію про продукт і зв’язки між продуктами, якщо їх кілька. По-друге, зніме величезне навантаження з продакт-оунерів.

Продаж або залучення інвестицій. Окрім притомного онбордингу, компанії іноді цікавляться продажем, партнерством, залученням інвестицій. Потенційному інвестору чи партнеру недостатньо зовнішньої картинки та обіцянок, що все працює. Він має розуміти, як усе влаштовано зсередини. А для цього потрібно мати відповідну документацію, яка чітко та інтуїтивно зрозуміло описує продукти та їхні функціональні аспекти.

Частенько буває, коли описуєш продукт постфактум, знаходиться якийсь функціонал, про який ніхто навіть не здогадується та не може пояснити, звідки він взявся та як воно працює, бо ніхто не документував його створення. Такий функціонал може роками жити в продукті. А це означає, що на екрані завжди буде непомітна кнопка чи зайвий рядок у формі, які у кращому разі не мають жодного функціонального навантаження.

Загалом якісно підготовлена документація — це обличчя продукту компанії та (не)зайве підтвердження цінності самої компанії. Також це знак якості роботи кожного спеціаліста, залученого у проєкті, і команди загалом.

Стандарти та підходи до аудиту документації

Мій невеликий досвід в аудиті документації виявив, що це комплексний процес із багатьма невідомими. Я довго вивчала інформацію в мережі й зробила невтішний висновок: стандартів і чітких правил досі не існує. Але є best practices. Вони ґрунтуються на індивідуальному та колективному досвіді техрайтерів і їхніх команд.

Кінцева мета команд, які розробляють продукт, і техрайтера, який займається аудитом, — не вбити одне одного до завершення аудиту. Я навіть переконана, що створити ці стандарти та рекомендації усе-таки можливо. Колективний розум — велика сила.

Етапи та часові межі

Треба бути готовим, що аудит і подальша робота над впровадженням його рекомендацій займуть від кількох тижнів до кількох місяців. Умовно весь процес можна розділити на такі етапи:

Вивчення наявної документації. Здебільшого вона технічна і частенько неактуальна.
Розроблення рекомендацій для усунення недоліків. Їх, до речі, ніхто не читає, тому краще презентувати усно з гарною візуалізацією.
Старт роботи з продуктом. Вивчення самого продукту та розроблення стандартів до його опису відбуваються паралельно.
Розроблення єдиного стандарту написання технічної документації для всіх команд. Це опціональний пункт: його не уникнути, якщо це велика компанія, де працює багато розрізнених команд. При цьому не кожна команда має свого техрайтера, й усі змушені самі вести свою технічну документацію.
Формування культури техрайтингу в компанії. Це моя професійна заповітна мрія. Маю досвід, коли команди не сприймали техрайтера як когось важливого та потрібного.

Отже, не сподівайтеся, що вся ця історія закінчиться швидко. Ось як було в мене.

Перший місяць. Техрайтер збирає абсолютно всі документи, записи, читає кожен гайд, словник, політику, якщо такі є. Завдання — вивчити те, що є, знайти «дірки» у послідовності, виявити неактуальне, розробити план упорядкування того, що піддається впорядкуванню.

Джерело

Так я складала Audit Summary. Прогалини, структура, мова написання, заголовки, стиль чи його відсутність — все, що могло бути важливим, розписувала по пунктах.

Другий місяць. Коли все хоч трохи прояснилося і стало зрозуміло, наскільки «пацієнт живий», можна перейти до лікування локальних болячок — сконцентруватися на конкретному проєкті (продукті) або на конкретній ділянці (команді).

Тут уже можна починати складати рекомендації з написання нової документації, збирати термінологію тощо. Зі свого досвіду скажу, що навіть в одній команді люди можуть по-різному підписувати один і той самий функціонал: англійською, рунглішем, транслітерацією з усіх можливих мов світу. А ще команди люблять абревіатури — це взагалі окрема історія збочень.

Джерело

Чернетка інструкції для техрайтерів: я люблю одразу визначати «правила гри» і завжди кажу по пунктах — так пишемо, так не пишемо. Пояснення не розписую, обговорюємо й узгоджуємо все усно. Далі йде такий собі чек-лист для техрайтера —лише найголовніше.

Третій місяць. Щойно ми з’ясували, яких стандартів і підходів не вистачає, та почали описувати їх, уже маємо певний план дій для їх запровадження.

Нагадаю, це потрібно, якщо у вас кілька команд, а ви один-єдиний техрайтер і фізично не маєте змоги писати технічну документацію для кожної команди. Тому наша ціль — допомогти командам вести свою документацію добре, а головне — стандартизувати підходи. Так ми полегшуємо життя всім.

На цьому етапі чимала частина продуктової документації верхнього рівня вже опрацьована та зведена до єдиного стилю, прогалини заповнено, неактуальну інформацію видалено й зібрано чимало даних щодо всіх продуктів, які використають у наступних статтях.

Джерело

А це коротенький вступ до великого мануала, який буде складатися з гайдів, які будуть складатися зі статей... Але не це головне, і навіть не зміст, — зміст ще зміниться не раз. Головне, що ним уже може користуватися кожен охочий. Люблю структурувати так: вступне слово, про що документ; зміст; розділи; додаткові посилання на суміжні статті виношу в кінець матеріалу.

Четвертий місяць. Стандарти написання технічної документації вже потроху впроваджені — можна додатково провести навчальні сесії для команд. Отже, час стандарти коригувати.

Так, ви прочитали правильно. Навіщо коригувати те, що щойно створили?

Тому що всі команди різні. Рівні сприйняття, довіри, зрештою бажання щось змінити у своїй роботі теж різні. Не можна загнати всіх в одну клітинку. Але можна уніфікувати підходи, щоб усім було зручно та зрозуміло, як працювати. Крім того, вже можна фіналізувати «хвости», які залишилися з третього місяця.

А якщо у вас декілька команд і декілька продуктів, які між собою ще й поєднані у певних процесах, всі ці чотири місяці доводиться сидіти на шпагаті. Звідси на першому етапі виникає певна сумбурність: неможливо передбачити, якою вийде структура продуктової документації, якими будуть назви статей, навіть те, якими мають бути їхні візуальні компоненти. Кожна компанія, як і її продукти, дуже індивідуальні.

Не кожна команда радіє аудиту документації

В ідеальному світі команди, щойно створивши новий продукт чи фічу, звертаються до техрайтера із запитом описати нове рішення. Від цього виграють усі: команди отримують буквально письмове підтвердження своєї роботи. Хоч у резюме записуй: ось, що я створив, ось, як воно працює. Компанія бачить, з чого складається її продукт, «відчуває» його. А техрайтеру багато не потрібно — задоволення, що все належним чином описано. Цінник усіх трьох сторін, повірте мені, тільки зростає від проактивності команд.

У реальному світі доводиться все описувати «на вчора» та щоденно долати перепони.

Будемо відвертими, ніхто не хоче звалювати собі на плечі додаткову задачу, якою б благородною не була її мета. На моїй практиці були команди, які намагалися будь-що відкараскатися від «непотрібної» формалізації процесів, зайвих розпитувань, навіть були випадки повного ігнору.

Справа може ускладнитися, якщо техрайтер ще й не перебуває фізично в одному приміщенні з командами. А сьогодні, коли вирує пандемія і ми всі працюємо віддалено, контакт зводиться до кнопки «надіслати повідомлення».

Моє рішення — шукати однодумців.

Неможливо вмовити людей нудними запевняннями, що має бути порядок і що всі від цього порядку виграють. Але можливо зацікавити, показати, що інвестувати трішки їхнього часу та уваги зараз — це зекономити години, ба навіть тижні зусиль зовсім скоро.

Одразу до списку потенційних «прихильників» можна вносити продакт-оунерів, бізнес-аналітиків, проєктних координаторів. Вони зазвичай дуже зацікавлені в тому, щоб у продукті все було розкладено по поличках. Звісно, попередньо потрібно ознайомитися, «продати» їм ідею аудиту документації так, щоб вони жили його перевагами, пропагували як добро серед своїх команд.

Також обов’язково боріться за любов та увагу тестувальників і розробників. Вони — джерело найцікавішої інформації про продукти, а якщо пощастить, ще й хранителі цінної технічної документації.

У розмовах з можливими союзниками я тисну на те, що якісна документація — це додаткова цінність команди та кожного спеціаліста. Найбільш часті заперечення такі:

«Наша цінність — це продукт, який ми створили». Згодна. Але для стороннього спостерігача це комплексна «обгортка» з логотипом компанії, за якою не видно роботи конкретних експертів.
«Наша цінність — це написаний код». І знову згодна. Але здебільшого похвалитися кодом можна лише перед тими, хто його розуміє, і тільки якщо це не заборонено договором про нерозголошення. Зовні ж код майже ніхто не бачить і не розбирає.

В обох випадках документація — можливість показати себе. А якщо вона міститься у вільному доступі, для команди це можливість обґрунтувати свої вміння та навички.

Іноді техрайтеру знадобляться і софт скіли, інакше кажучи, народні методи: витягнути потрібну людину на прогулянку / пиво / танці. Це допомагає налаштувати вас на одну хвилю.

А далі — як у мелодрамі. Команди до вас як до техрайтера уже звикли, хоча ви їх продовжуєте іноді дратувати. Капцями не кидаються, і то вже добре. Ще трохи часу — і здійсниться мрія техрайтера: вони самі прийдуть з пропозиціями щось описати в документації. А якщо вони не забули покликати вас на свої зустрічі-грумінги, то це вже любов!

Onsite-аудит vs outsource-аудит

Аудит документації, як і будь-який інший, можуть проводити як внутрішні, так і зовнішні експерти. Звісно, тут є свої переваги й недоліки, але єдиного правильного рішення не існує: все залежить від того, які цілі визначило керівництво.

До того ж не всі компанії можуть собі дозволити тримати команду техрайтерів. А іноді зовнішня консультація потрібна, щоб удосконалити певні процеси чи просто перейняти новий досвід.

Зовнішній аудит — це незамилений погляд на документацію та можливість отримати актуальні рекомендації для команди техрайтерів. Навіть якщо у компанії немає техрайтера, це шанс стандартизувати документи, а отже, підвищити цінність продукту. Однак зовнішній аудит — це ще й ризик розголошення інформації про інтелектуальну власність компанії.

Для техрайтера провести аудит в іншій компанії — це теж неабиякі переваги: від вивчення нових процесів до вдосконалення своїх навичок.

Внутрішній аудит документації — явище рідкісне. Якщо чесно, я не чула, щоб хтось його проводив. Звісно, не беремо до уваги великі компанії з міжнародним досвідом, для яких такі процеси — звичайна річ. Як на мене, якщо компанія дозволила собі мати техрайтера або навіть цілу команду, то внутрішній аудит документації має бути обов’язковим, проводитися з певною регулярністю та за певними процедурами.

(Не)фінансовий результат

Розумію тих, хто хоче виміряти якість і цінність аудиту документації в грошах. Але тут прямого зв’язку з прибутками немає.

Утім, ось вам, наприклад, контрольні запитання. Скільки може зекономити / заробити компанія від того, що:

команда не буде витрачати час на те, щоб вводити новачків у курс справи, ознайомлювати з продуктом загалом чи розповідати докладно про якийсь функціонал, а витратить ці години або навіть дні на безпосередні обов’язки (код, тестування, реліз тощо)?
нова людина в команді швидше ознайомиться з продуктами компанії, елементарно дізнається, де можна знайти необхідну інформацію про вже створений функціонал?
служба підтримки матиме менше навантаження, а користувачі знайдуть потрібні відповіді у документації?
команди матимуть додаткову інформацію про те, як працює продукт їхніх колег з інших команд (суміжного функціонала чи продукту), а отже, узгодять та уніфікують процеси за взаємопов’язаними проєктами?

Список запитань можна продовжити, адже кожна команда та компанія отримає свою цінність від такого аудиту. А відповідь на них одна: добре описана документація значно полегшує життя всім залученим у створення та підтримання продукту сторонам.

Крім того, як на мене, аудит документації саме зараз набуває актуальності. Довкола вирує пандемія, світ вступає в нову фінансову та економічну кризи, компанії змушені переосмислювати свої процеси та стратегії розвитку. Аудит документації неабияк допомагає цьому переосмисленню, а можливо, навіть стане джерелом пошуку стратегічно важливих рішень.

А ваша компанія проводить чи планує провести аудит документації? Як це відбувається у вас?

Опубліковано: 11/02/21 @ 01:00
Розділ Різне

SEO Блог