Хто у вас на проєкті пише документацію?

Хто у вас на проєкті пише документацію?

Чи ви живете без неї, як в мемі про тімліда, який каже «Я і є твоя документація!»

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

Особливо якщо це [прости боже] скрам зі своєю кросс-функціональністю та з принципами «Working Software Over Comprehensive Documentation» та «Individuals and Interactions Over Processes and Tools».

Тож, хто у вас її пише та підтримує? Тімлід? Піем? Всі? Ніхто?

Чи люди, код з коментарями та тести і є носіями бізнес-логіки?
Як то кажуть, самодокументуючий код?

👍ПодобаєтьсяСподобалось1
До обраногоВ обраному0
LinkedIn
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter

Я как-то раз написал описалово по API сервера на 80 страниц мелким текстом. Там была только одна нужная информация — какие параметры для чего нужны, с примерами. Этот мануал так никто до конца и не дочитал. В конечном счёте один чувак сказал сократить всё это до 5 страниц, без чего работать не будет. Ну я и сократил, этот вариант осилили.

Ти так запитуєш ніби ту документацію хтось би читав коли вона була б.

---

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

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

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

Спеки (PRD) пишуться PM-ом. Фокус робиться на тому як нова API/feature/etc буде використовуватись клієнтами, у чому користь для клієнтів. Я читав кілька десятків таких документів, «бізнес логіки» не бачив там ні разу.

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

Scrum
Усі пишуть кожен потроху і усюди від діаграм до доксігена

У нас — стартап, що орієнтується на опен-сорс стандарти, тож, документація на продукт — публічна і пишуть та покращують її всі потроху :)

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

New starters, звісно ж. Всіх заставляю писати доки. Багато свіжого повітря приносять в проект.

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

QA зазвичай, це наша робота. Ще аналітики трохи пишуть

Не знав що QA пишуть документацію, думав що тільки тестують

А хто ж пише сценарії, сьюти, тест-кейси, автотести, тестові дані?

о в нас зараз така тєма, документація живе в голові тім ліда і дизайнера, намагаюся її з неї дістати

Як би сильно не хотілось мати документацію, але по факту за 7 років ніколи її ніде не бачив. Що в аутсорсах, що в продуктах. Звичайно всі мої проекти були НЕ ентерпрайз. Один раз тільки був PDF на 180 сторінок з описом всього функціоналу, де 50% інфи було outdated.

Зараз працюю в «компанії» яка має напевно штук 20-30 під-проектів — опенсорси і внутрішні. І в принципі я навіть хз нащо тут документація. Щоб її підтримувати, треба фуллтайм людина на зарплаті, яка все одно наврядчи услідкує за всим. А нові члени команди набираються так, щоб вони вміли трохи включати клепку й розбиратися в тому що є — поки що проблем не було :)

https://passo.uno/tech-writers-letter-to-developers/

Техрайтер пише. Архітектор пише, коли є час :)

Є така позиція — Технічний письменик. Він і пише :D
А ще є бізнес-аналітики. Вони теж пишуть)

Очень редко кто пишет документацию. тем более что она имеет смвысл для коробосных проектов.. какой смысд доекментации нак проект под заказ гшде заказчик и так знает что там потому как его требования

Документація найбільш потрібна коли приходить нова людина на проект і треба її ввести в курс всього як там що працює =(

Документація потрібна щоб швидко згадати деякі дрібні деталі по проєкту які хтось забув і відштовхуватись від них.

Підписатись на коментарі