Як я пишу документацію і чому це нагадує створення продукту

💡 Усі статті, обговорення, новини про тестування — в одному місці. Приєднуйтесь до QA спільноти!

Вітаю! Мене звати Олександра Пасенченко, я General QA Engineer в OBRIO, але моя менеджерка називає мене «профі з документації». Коли мене питають, які робочі задачі мені найбільше подобаються, одна з відповідей — люблю писати документацію. І я відповідала так ще до того, як використання ШІ стало мейнстримом. Так, я готова ловити здивовані погляди :)

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

Процес створення документації нагадує мені процес створення продукту в мініатюрі, тому пропоную розібрати його за стадіями Software Development Life Cycle (SDLC).

1. Планування

Перед тим як створювати новий продукт або додавати нову фічу, слід зрозуміти — а чи потрібно це взагалі? Які проблеми вирішить цей продукт або фіча?

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

Тож коли варто створювати документацію? Які проблеми вона може вирішити?

• Для онбордингу новеньких. На початку роботи виникає багато питань: як налаштувати тестове середовище, як створити користувачів з різними доступами, як тестувати певний функціонал? Наявність документації для онбордингу допоможе новеньким не розгубитися і плавно увійти в курс справи.
• Для мінімізації bus factor. Якщо колеги багато разів звертаються до вас по певну інформацію. Скажімо, ви тестуєте платежі, і знаєте про них все. Але з платежами працюєте не тільки ви, і час від часу вас відволікають питаннями «А є картка для перевірки недостатньої суми коштів?» або «А як зробити рефанд?». Винесення цього в документацію заощадить час вас і ваших колег, і до того ж дозволить вам систематизувати знання про платіжні системи та їх особливості.
• Для систематизації інформації. Буває, що при виконанні задачі потрібно провести справжнє розслідування для збору інформації. І після годин пошуку за ключовими словами в документації проєкту та в таск-трекері, переглядів дизайну та численних синків з колегами, нарешті, пазл складається. Результат такого розслідування було б добре винести в документацію і поділитися нею з командою.
• При впровадженні нового процесу або технології. Наприклад, ви переходите на новий фреймворк для автотестів, і вам треба заонбордити колег в нього. Гарною ідеєю буде провести зустріч і наживо показати, як користуватися цим фреймворком (і не забудьте поставити на запис!). Але кожен раз передивлятися відео, якщо виникає питання, звучить не дуже user-friendly. Тому чудовим доповненням до відео стане також документ з принципами роботи з цим фреймворком.

2. Аналіз

Отже, ми вирішили — новій документації бути!

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

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

Варто поміркувати над таким:

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

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

3. Дизайн

Скоуп роботи визначено, а значить, час розробити структуру нашого документа.

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

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

4. Розробка

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

Поради для створення інструкцій:

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

  

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

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

• Використання описаних в гайді інструментів може передбачати особливі доступи — наприклад, корпоративний VPN або база даних. Важливо зазначити це, а в ідеалі — також додати посилання на інструкцію, як його налаштувати, або до кого можна звернутися, щоб людина при виконанні кроків з гайда не блокувалася на цьому моменті.
• Цей пункт залежить від цільової аудиторії документації, але якщо ви робите його для внутрішньої команди або у вас немає обмежень щодо офіційного тону, можна де-не-де додавати в текст жарти або меми. І вам буде цікавіше створювати таку документацію, і колегам буде веселіше читати — суцільний win-win. В уже згаданій документації з переходу на Playwright я описувала особливості синтаксису тестів, зокрема використання async/await, і не змогла утриматися від того, щоб не додати цей мем:

  

5. Тестування та інтеграція

Ура, основну частину роботи виконано!

Перш ніж релізити нову фічу, її варто протестувати. Так само з документацією — перед тим, як віддати її «в люди», проводимо тестування:

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

6. Підтримка

Ваша документація використовується командою і приносить користь, і це прекрасно!

Але є одне «але» — вона швидко стає неактуальною, особливо в динамічних проєктах. Що з цим робити? Як би банально це не звучало — оновлювати. До цього можна підходити так:

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

7. Висновок

Ми з вами пройшлися по всіх етапах створення документації: від планування до постійної підтримки. Як бачимо, створення документації це не просто «написати текст», а цілий процес, подібний до Software Development Life Cycle (SDLC).

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

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

Отже, документація — не просто формальність, а база, ґрунт, фундамент, на якому будується успішний, якісний та підтримуваний програмний продукт. Це інвестиція, яка окупається багаторазово протягом усього життєвого циклу проєкту.

А які у вас лайфхаки, що спрощують роботу над документацією? Поділіться у коментарях!