Стендап Сьогодні 📢 Канал в Telegram @stendap_sogodni

🤖🚫 AI-free content. This post is 100% written by a human, as is everything on my blog. Enjoy!

08.02.2023

Документація по проєкту

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

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

Документацію має бути легко писати, бо написання — це вже робота, та до того ж побічна. Тож додати нотатку має бути можливо з мінімумом зусиль. Цю цінність я зрозумів на важкому досвіді, що щоб створювати на кожну зміну Pull Request - ні в кого немає часу. Взагалі Git в прямому вигляді незручно використати — бо треба робити commit, а потім push, а потім може ще й конфлікти вирішувати.

Документацію має бути легко шукати, це не менш важливо. Зміст та навігація — це добре, але на практиці чим більше напишуть (що добре!), тим складніше підтримувати штучну систему організації. Краще, коли можна шукати нотатки за текстом, а також за тегами.

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

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

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

Який інструмент все це підтримує? Я теж хотів би знати. :)