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

Отримавши завдання оновити документаційну базу для свого відділу, Наталка Терент’єва, Data Analyst AdConnect у компанії appflame, підійшла до цього не лише ґрунтовно, а й креативно. І в результаті створила документацію, яку читають із користю й задоволенням та ставлять за приклад іншим командам. Як їй це вдалося? Наталка ділиться своїм досвідом і практичними порадами.

Як і більшість продуктових ІТ-компаній, ми в appflame динамічно розвиваємося в багатьох аспектах: продуктах, інструментарії, команді. І рано чи пізно (здебільшого рано) в кожного з нас настає момент сократівського усвідомлення: «Я знаю, що нічого не знаю». Тобто обсяг інформації, необхідний для ефективної роботи, стає настільки великим, що не вміщається в одну голову. Щоб запобігти цьому, потрібна колективна свідомість, яка акумулюватиме в собі знання кожного. Тобто спільна база знань. Тобто документація.

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

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

Навіщо компанії документація?

Основне — це вдала інвестиція. Якісна й актуальна документація починає приносити результат одразу й окупає ресурси, спрямовані на її створення, в довгостроковій перспективі.

Щоб обґрунтувати для себе необхідність написання нової документації для Data Science команди, я розділила проблеми, спричинені її відсутністю, на дві умовні групи.

Коротко- та середньострокові наслідки поганої документації чи її відсутності:

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

Довгострокові наслідки поганої документації чи її відсутності:

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

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

Історія створення нашої документації

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

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

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

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

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

Працювати над документацією мало б бути не надто весело. Але мені дали повну свободу дій, тож як можна було цим не скористатися? Документація замайоріла мемами (загальновідомими й нашими внутрішніми), сленговими слівцями та місцями суржиком. Було навіть трохи лайки — для родзинки, так би мовити.

Я намагалася писати так, наче розповідаю все наживо: ставити запитання, звертатися до читача на «ти», робити мову максимально неформальною там, де це можливо. Наприклад, ось тут:

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

Що ми отримали в результаті? Приклад структури 

Робота над документацією тривала приблизно три місяці як найменш пріоритетне завдання. Гадаю, на неї йшло 30-40% робочого часу.

На виході ми отримали докладний опис усіх основних процесів та інструментів для команди аналітики. У результаті вийшла така структура:

• розділ для новачків;
• інструменти; 
• SQL;
• репорти та A/B тести;
• ML моделі;
• регулярні події та процеси (від дейліків до квартального планування);
• лог із ресьорчами й інсайтами;
• невирішені завдання й гіпотези.

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

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

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

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

• Відповіді на основні робочі питання, що виникають у всіх без винятку нових колег. У результаті істотно зменшився час на онбординг нового співробітника. Перебуваючи в ролі onboarding buddy вдруге, я скоротила час, який приділяла новій колезі, більш ніж удвічі. І це — без втрати якості. А наш хед зміг делегувати частину обовʼязків з навчання новенької, оскільки тепер був упевненим, що вона отримає всю необхідну інформацію.
• Лог із ресьорчами, де фіксуються, зокрема, цікаві інсайти про продукт. У результаті стало менше повторень схожих завдань, покращилося загальне розуміння продукту та користувачів. І як наслідок — підвищилась ефективність роботи аналітиків.
• Типові запити з виведенням усіх основних метрик. У результаті істотно підвищилася точність репортів, покращилося розуміння бази даних.
• Лог із невирішеними завданнями та гіпотезами, куди записуються певні питання без відповіді. У результаті будь-хто з команди може взяти на себе розв’язання завдання, яке виявилося не під силу колезі чи на яке не знайшлося часу в інших. Тепер проблеми розв’язуються більш ефективно, а A/B тести запускаються раніше й сетапляться більш правильно.

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

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

Факап-хвилинка: пустий «Словник аналітика»

Не обійшлося й без дрібки факапів. Я прагнула максимально залучити команду до написання документації, адже значна частина безпосередньо стосувалася їхньої роботи, тож ніхто не написав би її краще за них. Частково мені вдалося їх мотивувати: думаю, завдяки тому, що ефект від новоствореної частини документації вже став помітним. Для більшого залучення я створила статтю під назвою «Словник аналітика», яка мала містити пояснення аналітичної термінології, щоб у нових людей не виникало запитань по типу «Що таке CTR?». 

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

Як нам все вдалося? Практичні поради

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

Як підготуватися до написання?

1. Долучати до написання потрібно всіх без винятку членів команди. Але краще призначити відповідального, який буде приділяти проєкту вдосталь часу, зможе продумувати структуру, модерувати контент, вичитувати текст на помилки, врешті-решт.
2. Основний каркас варто продумати заздалегідь. Інформація має бути повна та структурована, для цього можна використовувати принцип МЕСЕ (Mutually Exclusive Collectively Exhaustive — принцип структурування інформації, за якого її елементи повинні бути взаємовиключними та всеохопними).
3. Серед усіх елементів важливо знайти місце для правил створення самої документації: що саме ми документуємо, з якою метою та в якому стилі, складники типової статті й інші рекомендації щодо контенту. Це спростить модерацію в майбутньому.

Як, власне, писати документацію?

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

У кожній описовій статті бажано мати короткий набір правил. Наприклад, у статті з переліком репортів — правила створення репортів. У статті про A/B тести —  правила запуску A/B тестів. У статті про регулярні мітинги — правила проведення мітингів.

Не варто надмірно формалізувати мову, якщо хочете, щоб статті читали. Якщо відчуваєте, що читач засне на середині статті, напишіть йому: «Прокинься, залишилося зовсім трішки!».

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

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

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

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

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

Документація написана. Що далі?

1. Документація не має практичного сенсу, якщо її актуальність не підтримується. Зміни варто вносити оперативно — щойно вони відбулися.
2. Якщо постає необхідність додати щось нове, краще додавати відразу. Бодай коротко — так воно не загубиться в глибинах памʼяті, а розписати тему в подробицях можна пізніше, коли буде час.
3. Привчайте колег користуватися документацією. Немає сенсу проговорювати зайвий раз те, що вже описано. Коли це увійде у звичку, питань стане істотно менше. Раніше мені ставили запитання, зараз — просять посилання на документацію.
4. На цьому етапі модерація стає ще важливішою, адже з плином часу основна ідея дещо втрачається, частіше трапляються нові статті, які вибиваються із загальної канви. 
5. Якщо з часом розвиток бізнесу ставить нові вимоги до документаційної бази, можливо, має сенс проявити гнучкість і переформатувати документацію.

Що в підсумку?

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

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

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

Читайте також

Хто такий data scientist і з чого почати, якщо ви хочете ним стати?

Як побудувати робочий процес у команді в умовах війни

Управління проєктами у повсякденному житті: основні етапи й інструменти