Документация: тот минимум, который окупается

Документация: тот минимум, который окупается

Полная документация не пишется никогда — это факт, с которым проще смириться. Но есть несколько страниц, которые экономят команде недели, и их стоит держать в порядке.

Первое — как поднять проект у себя. Пошагово, с версиями и с описанием граблей. Эту страницу читает каждый новичок, и по ней он судит обо всей команде.

Второе — карта системы на одном экране: какие части есть, кто с кем разговаривает, где данные. Без неё каждый новый человек собирает картину в голове по кусочкам месяца три.

Третье — решения и причины. Не «мы используем такую-то очередь», а «мы выбрали её, потому что нужен был вот такой сценарий; альтернативу отбросили вот почему». Через год этот текст спасёт вас от спора по кругу.

Четвёртое — что делать, когда сломалось. Куда смотреть, кого звать, какие ручки крутить.

Всё остальное можно не писать. И держите документацию рядом с кодом, а не в отдельной системе, куда никто не заходит: то, что не открывают, устаревает мгновенно и начинает вредить.

IT Санкт-Петербург — t.me/itspb_news