Почему разработчики пишут ужасную документацию

28.10.2013

Сегодняшняя заметка Джеки Сэмюэлс (Jacquie Samuels), консультанта в области технических коммуникаций, DITA, CMS, посвящена причинам, по которым разработчики не должны писать документацию к собственным продуктам.

Мир разработки программного обеспечения может быть стремительно развивающимся и иногда приходится очень сильно напрягаться, чтобы успеть подготовить всё к релизу. Если у компании нет отработанного процесса или отдела технической документации, часто писать документацию на продукт просят разработчиков. Действительно, кто знает продукты так же хорошо, как они?

Даже авторитетная компания может сесть в лужу с документацией, написанной разработчиком. Например, одна компания, разрабатывающая программное обеспечение, обычно пропускающая контент через отдел документирования, напортачила на небольшом, быстром проекте, который был насколько спонтанным, что никто даже и не подумал сказать: «Хорошо бы сказать группе документирования, что ведётся работа над новым продуктом, потому что, знаешь, клиентам как бы нужна документация к продукту». За день до релиза они, наконец, сказали об этом и отправили какой-то разработанный самостоятельно ими контент на быструю вычитку техническим писателем (да, этим писателем была я) в плане правки оформления, орфографии и грамматики – больше времени ни на что не осталось. И в таком виде это отправилось клиенту.

Клиент потратил три дня на продукт, а потом сказал: «Мы разве говорили, что хотим продукт прямо сейчас? Ну, нам бы хотелось, чтобы вы потратили некоторое время на то, чтобы написать больше документации перед тем, как мы его возьмём». Да, правильно, они вернули продукт из-за плохой документации.

Из-за чего документация была плохой? Разработчики, которые её написали, знали продукт очень хорошо, у них была (честно) хорошая команда по английскому языку, и продукт сам по себе не был таким уж сложным. Так что пошло не так?

Ответ заключается не в том, что разработчики не могут писать хорошо или не могут писать документацию. Они бы точно смогли… если бы не разрабатывали этот продукт. Проблема в том, что разработчики слишком глубоко погружены в свой продукт. Не поймите меня неправильно; это очень хорошо. Если бы разработчики не были так погружены, продукт был бы ужасным, недоделанным и квазифункциональным. Однако разработчики просто не могут занять позицию, которая требуется для документации – контент, написанный с позиции пользователя, даёт пользовательскую точку зрения, позволяет не допустить непреднамеренного искажения, которое может допустить разработчик.

Для написания удобного контента должен произойти значительный скачок. Точка зрения разработчика при написании документации – «это мой продукт; вот как использовать то, что в нём есть». Технический писатель, однако, создаёт контент, думая так: «Привет, пользователь, вот как ты будешь делать те вещи, которые хочешь получить от этого продукта».

Так что проблема не в человеке; это роль. Для написания технической документации требуется фокусироваться на пользователе, что просто невозможно, когда вы занимаетесь разработкой кода неделями, месяцами, годами. Это лишь дополнительный бонус – технические писатели тоже тратят года, улучшая инструменты, языковые навыки и техники для того, чтобы создавать качественную документацию с лёгкостью.

Источник: Why Developers Write Horrible Documentation

Тэги: опыт, профессия, роли