Представьте: вы уходите в отпуск, а через две недели возвращаетесь к своему же коду. Открываете файл... и чувствуете себя археологом, который пытается расшифровать древние письмена.
Знакомо? Это и есть жизнь без документации.
Что такое техническая документация?
Это совокупность материалов, которые описывают систему: как она устроена, как с ней работать и почему она сделана именно так, а не иначе.
Основные виды техдока:
📌README — первое, что видит любой разработчик. Краткое: что это, как запустить, как использовать.
📌API-документация — описывает эндпоинты, параметры, форматы ответов. Без неё интеграция превращается в угадайку.
📌Архитектурная документация — объясняет, почему система устроена именно так. Особенно ценна, когда через год никто не помнит, зачем так сделали.
📌Changelog — история изменений. Просто и честно: что добавили, что сломали, что починили.
📌Runbook — инструкции на случай нештатных ситуаций. Что делать, если всё упало в 3 ночи и нужно действовать быстро.
Почему команды игнорируют документацию?
Потому что писать её — скучно, а польза не очевидна здесь и сейчас.
Но вот жёсткая правда: каждый час, сэкономленный на документации сегодня, превращается в три часа онбординга нового разработчика, пяти часов дебага через полгода и бесконечных вопросов в чате.
Золотое правило
Хорошая документация отвечает на три вопроса:
— Что это делает?
— Как с этим работать?
— Почему это сделано именно так?
Если на все три есть ответ — документация работает.
Пишите документацию не для галочки, а для людей. В том числе для себя через полгода. Вы скажете себе спасибо. 😉
Всем хорошего вечера! 🔥
Для сотрудничества и предложений пишите на почту cooperation@martinscode.tech или в Telegram: @mscotech
Martin.s Code — студия, где идеи обретают форму
#interest