Документація в проді потрібна не “для галочки”, а щоб код можна було підтримувати після того, як автор піде на вихідні або зміниться команда. Ідеальна документація модуля — коротка, конкретна, прив’язана до реального коду: які екрани є, які правила доступу, які стани, де основна логіка, які побічні ефекти, як дебажити, як додавати новий фільтр/поле без ризику. Вона має відповідати на два питання: як це працює зараз, і що робити, коли треба змінити.
Починайте з “що це за модуль” в одному абзаці. Назва модуля і його бізнес-роль: що він робить, які сутності керує, хто ним користується. Це знімає головне питання “з якою частиною системи я маю справу”. Далі — короткий список сценаріїв: створення, редагування, архівація/видалення, зміна статусу, перегляд списку з фільтрами. Не треба описувати кожну кнопку — тільки сценарії.
Далі розділ “Як це працює” — опис флоу. Тут важливо не повторювати код, а показати шлях запиту: route → controller → FormRequest → service → DB → activity → redirect/response. Для кожного основного сценарію (create/update/change status) достатньо 3–5 речень: що приходить на вхід, де перевіряються права, де валідація, де транзакція, що записується в activity, які jobs стартують. Якщо модуль використовує кеш/черги — це треба згадати тут же: “після publish диспатчиться job для…”.
Потім “Доступи і видимість” — найважливіший блок підтримки. Ви фіксуєте: які ролі існують для модуля, які дії кому дозволені (viewAny/view/create/update/delete/спецдії), і як саме реалізована видимість записів (scope visibleTo або query в сервісі). Тут критично зазначити правило: фільтри ніколи не розширюють доступ — базовий scope застосовується завжди. Це той пункт, який рятує від витоків, коли хтось “додав фільтр по user_id”.
Далі “Фільтри, сортування, пагінація”. Коротко: які GET-параметри підтримуються, по яких колонках фільтруємо, які значення дозволені (whitelist для статусів), яка дефолтна сортировка, яка пагінація (perPage), чи зберігається query string. Якщо є важливі індекси під ці фільтри — обов’язково згадати: “фільтр по date/status спирається на індекс …”. Це прямий місток “як підтримувати продуктивність”.
Далі “Стани і переходи” (якщо є статуси). Це коротка state machine: які статуси існують і які переходи дозволені. Наприклад: draft → review → published; published → archived; редагування дозволено тільки в draft/review; delete заборонено після published. Тут же фіксуєте інваріанти: “posted не редагується”, “published без slug — заборонено”. Це найчастіше ламають новачки, тому документація має бути прямою.
Далі “Сервісний шар” — мінімальна карта методів. Не треба перераховувати весь код, але треба показати “точки входу”: які основні public-методи сервісу існують і за що відповідають. Наприклад: create(), update(), archive(), publish(). Для кожного — 1–2 речення: що робить, чи використовує транзакцію, які побічні ефекти запускає (jobs/notifications). Це допомагає підтримці: коли треба щось змінити, людина знає, куди лізти, а не шукає по всьому проекту.
Далі “Activity log і нотифікації”. Тут ви фіксуєте: які події логуються (ключі/типи), де вони записуються (в сервісі), які поля в activity важливі (actor, entity, action, correlation id), і які нотифікації відправляються (канали, кому, за яких умов). Дуже корисно додати правило ідемпотентності: “нотифікації не дублюються при retries” — і де це забезпечено.
Далі “Черги / Scheduler / Кеш” — тільки якщо використовується. Вказуєте: які jobs є, в якій черзі вони працюють, що вважається failed, де дивитись failed jobs, які timeout/retry очікування. Для scheduler — які команди запускаються і що буде, якщо scheduler не працює (health-check). Для кешу — що кешується, TTL, інвалідація (події або теги). Цей блок має бути короткий, але конкретний: “як знайти проблему” і “що перезапустити/перевірити” на рівні системи.
Далі “Тести” — як мінімум, список критичних тестів і що вони гарантують. Не треба описувати кожен assert, але треба назвати категорії: доступи, видимість, валідація, статуси, фільтри, транзакції, jobs (якщо є). І коротко: “як запускати” (команда), і “що робити, якщо падає” (типові причини). Це дуже допомагає новачку: він не сприймає тести як магію.
Нарешті — “Як підтримувати і розширювати” — найцінніший розділ. Тут ви даєте 5–10 чітких правил, які не можна порушувати. Наприклад: не обходити базовий scope видимості; нові фільтри додавати через when() після scope; не робити orWhere без групування; не тягнути hasMany на список; будь-яка зміна стану — через сервіс; activity пишеться в транзакції; нові поля в формі — через FormRequest + заповнення тільки validated; додав новий фільтр/статус — додай тест. Це і є “як підтримувати”, без води.
Дуже практична порада для формату: одна сторінка Markdown на модуль. Вгорі — коротко “що це”, далі секції: Flow, Access, Filters, States, Service, Activity/Notifications, Ops (queues/scheduler/cache), Tests, Maintenance rules. Цього достатньо, щоб людина відкрила файл і за 2–3 хвилини зрозуміла, де вона і що робити.
Висновок: хороша документація модуля — це коротка карта системи: як іде запит, де правила доступу, як працюють фільтри і стани, де головна логіка (сервіс), що пишеться в activity, які є фонова робота (черги/планувальник/кеш), які тести тримають контракт, і які правила не можна порушувати при розширенні. Якщо ви привчитеся писати таку “односторінкову” документацію після кожного повного модуля, підтримка перестане бути лотереєю.
