Почему программисты не пишут документацию
Разработчика Кислая Верму возмутила статья на medium.com о причинах, по которым программисты не пишут документацию. В частности, он не согласен с тем, что главная проблема — отсутствие хороших инструментов. По мнению автора, на самом деле есть две других основных причины. Вот они:
1. Это сложно
Первой причиной Кислай Верма называет сложность процесса. Подготовка документации — сложная и ответственная задача, которая требует организации мыслей, критического анализа и четкого выражения. Писать становится все сложнее: надо установить контекст, обосновать решения, а затем задействовать низкоуровневое мышление, ведущее к кодированию. Плохой код все равно будет «летать», плохая документация — нет.
2. Отсутствие документации не мешает доставке продукта клиенту
Если разработчик не пишет документацию, его работа все равно выполняется. Отсутствие документации не отменяет доставку продукта, а ущерб, нанесенный отсутствием документирования технических решений, проявляется не сразу. К тому же, в большинстве случаев можно кодировать «на коленке»: неорганизованная куча классов и методов в коде может работать, а вот бессмысленная куча слов и абзацев не сработает.
А что инструменты?
Кислай Верма считает, что для создания грамотной документации нужны инструменты, которые помогут на протяжении долгого времени эффективно собирать идеи для решения задачи. По мнению автора, Google Docs, Confluence и Markdown — плохие инструменты для этого. Он делает ставку на новое поколение приложений — таких как Notion и Roam Research.
Как составлять документацию
Автор считает, что единственный способ сделать процесс написания документации стабильным — сделать его легким, но обязательным. Вот что автор советует разработчикам:
- Напишите заметку, прежде чем написать код.
- Пишите просто — о чем подумали, что делаете и почему.
- Задокументируйте решения и их альтернативы. Вместо того, чтобы подробно документировать фактическую реализацию, которая может со временем измениться, сосредоточьтесь на документировании причин, по которым решения были внесены.
- Сделайте документацию доступной для поиска. Если ее невозможно найти, в ней нет смысла.
- Настройте возможность отслеживания изменений, вносимых в документацию.
Сообщить об опечатке
Текст, который будет отправлен нашим редакторам: