Почему программисты не пишут документацию

Разработчика Кислая Верму возмутила статья на medium.com о причинах, по которым программисты не пишут документацию. В частности, он не согласен с тем, что главная проблема — отсутствие хороших инструментов. По мнению автора, на самом деле есть две других основных причины. Вот они:

1. Это сложно

Первой причиной Кислай Верма называет сложность процесса. Подготовка документации — сложная и ответственная задача, которая требует организации мыслей, критического анализа и четкого выражения. Писать становится все сложнее: надо установить контекст, обосновать решения, а затем задействовать низкоуровневое мышление, ведущее к кодированию. Плохой код все равно будет «летать», плохая документация — нет.

2. Отсутствие документации не мешает доставке продукта клиенту

Если разработчик не пишет документацию, его работа все равно выполняется. Отсутствие документации не отменяет доставку продукта, а ущерб, нанесенный отсутствием документирования технических решений, проявляется не сразу. К тому же, в большинстве случаев можно кодировать «на коленке»: неорганизованная куча классов и методов в коде может работать, а вот бессмысленная куча слов и абзацев не сработает.

А что инструменты?

Кислай Верма считает, что для создания грамотной документации нужны инструменты, которые помогут на протяжении долгого времени эффективно собирать идеи для решения задачи. По мнению автора, Google Docs, Confluence и Markdown — плохие инструменты для этого. Он делает ставку на новое поколение приложений — таких как Notion и Roam Research. 

Как составлять документацию

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

• Напишите заметку, прежде чем написать код.
• Пишите просто — о чем подумали, что делаете и почему.
• Задокументируйте решения и их альтернативы. Вместо того, чтобы подробно документировать фактическую реализацию, которая может со временем измениться, сосредоточьтесь на документировании причин, по которым решения были внесены.
• Сделайте документацию доступной для поиска. Если ее невозможно найти, в ней нет смысла.
• Настройте возможность отслеживания изменений, вносимых в документацию.