Автор: @eantonov
Телеграм: Тимлид Очевидность
Обсудить: Чат канала в телеграм
Перефразирую известную фразу про бэкапы.
Люди делятся на два типа. На тех, кто не пишет доки, и тех, кто уже пишет.
Это мое мнение по большинству вопросов, связанных с документацией.
Плюсы
На мой взгляд, документация весьма полезна, хоть и требует определенного времени, дисциплины и усилий.
- У вас в команде есть человек, который знает, как делать одну штуку, и вы ходите всей толпой к нему, а когда он увольняется, плачете горючими слезами? Пусть напишет доку и отвечает страждущим ссылкой на доку, а потом увольняется сколько угодно. Его знания останутся в веках на письме.
- Вы делаете набор типовых действий раз в месяц-полгода-год и постоянно забываете, как же там правильно? Напишите доку с правильным алгоритмом действий и спите спокойно, выкинув из головы боязнь что-то забыть.
- Вы запрограммировали сложную задачу с развесистой бизнес логикой, а теперь ваш коллега приуныл, пытаясь внести правки? Или вы сами приуныли, потому что запрограммировали полгода назад и теперь смотрите на этот код, словно в первый раз? Напишите доку по этой бизнес логике сразу, порисуйте диаграммы всякие и не надо будет держать в голове все знания годами (а вы и не удержите).
- Вы договорились в команде делать так, а через месяц коллеги начали делать иначе (они забыли), а новички - еще иначе (они и не знали)? После того как договорились, напишите доку по регламенту и выдавайте её всем коллегам и новичкам. Тогда старые коллеги не забудут, а новые будут легко онбордиться.
Таких примеров можно приводить море.
Минусы
Однако есть и определенные сложности в написании документации:
- Нужно уметь понятно и структурированно излагать свои мысли письменно.
- Нужно иметь определенную долю дисциплины и времени, чтобы регулярно актуализировать доку. В противном случае устаревшая документация будет еще хуже, чем никакая.
- Бывают случаи, когда написание доки - это действительно излишняя трата времени. Например, вы делаете проект, отдаете его заказчику, получаете деньги и больше с ним дела не имеете. Или вы делаете проект, который провисит 2 месяца в проде и закроется, а подобный делать вам больше не понадобится (запаситесь хрустальным шаром для точного предсказания будущего).
Итог
Мое мнение, что плюсы ощутимо перевешивают минусы. Поэтому, если ваш менеджер говорит вам, что дока не нужна и это только трата времени, и вам не за это платят, вы можете помочь ему разобраться с ситуацией и показать этот пост. Если это не помогло, согласитесь с ним и не пишите доку, а потом, когда команда наступит во все грабли из раздела плюсов, дайте ему перечитать этот пост еще раз.