Три причины не писать документацию

Первая. Документация не больно то и нужна.

Представим себе небольшую команду разработчиков, занимающихся автоматизацией машиностроительного завода. Часть софта покупают, часть пишут сами. Семен Владимирович пришел на завод работать программистом в 1981 году. Остальные в 1988, 1993 и 1997. Самый молодой из разработчиков работает в команде последние 12 лет. Понятно, что в таких условиях все разработчики прекрасно знают операционную среду, заказчиков, пользователей и код. И вся документация на новую фичу трудоемкостью в два человеко месяца может умещаться на одном стикере.

Я предлагаю три метрики:

  • Средний опыт разработчиков. В данном случае это 19+ лет.
  • Средний опыт работы вместе. (21+16+16+12+12+12)/6= 15 лет
  • Средний опыт работы в предметной области

В вышеприведенном случае все характеристика очень высокие и документация содержится по большей части в голове. Но если эту четверку “уйти” и заменить дюжиной студентов под предводительством племянника владельца предприятия, то … На самом деле документация им уже не поможет.

Причина вторая. Некому писать.

Действительно, грамотно описать функциональные требования или глоссарий (я уж не говорю про нефункциональные или, тем более, концепцию), это гораздо сложнее, чем закодировать. В результате, вместо требований, которыми можно пользоваться получается скучнейшие “материалы 35 съезда” изложенные косноязычным тинейдрером, знающего только олбОнский, и то с пятого на десятое. Читать это невозможно. Документация становится Write Only. И, в конце концов,  от написания документации отказываются.

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

Причина третья. Команда не умеет читать.

А вот эта проблема по настоящему серьезная.

Типичный пример того, что никто не умеет читать документацию это фразы вида: «Цель проекта внедрения BTS Jira является автоматизация учета багов.»

Я понимаю, у аналитика писавшего ЭТО был неудачный день. Может зубы у ребенка резались и была бессонная ночь. Может быть гриппом болел и голова не соображала. Но то, что из всей команды никто не сказал “Булшит!”, это показатель неумения читать. Писать документацию в этом случае бесполезно.

Проблему усугубляет странная российская система подбора персонала, когда на место разработчика ищется инженер со скилами кодера. Вот типичнейший пример:

Разработчик Java
Требования:

* Обязательные:
Опыт разработки на Java, знание ООП;
Знание  HTML;
Знание и опыт работы с JSP;
* Желательные:
Опыт работы с каким-либо web-framework’ом (JSF, Struts, GWT, Wicked и т.д.);
Опыт работы с какой-либо AJAX-библиотекой (jQuery, Ext-JS, Prototype);
Опыт работы со Spring framework;
Опыт работы с  JDBC, JPA, Hibernate и подобными средствами (взаимодействие с БД);
Опыт работы с WebShpereAS;
Опыт работы с СУБД Oracle;
Опыт работы с EJB;
Опыт работы с Web-сервисами.

Написано, что ищут разработчика, а в требованиях нет ни навыков анализа, ни умения проектирования GUI ни даже навыков верификации собственного кода. Ни-че-го.

Проводя курсы по написанию документации, я сделал вывод, что на то, чтобы научить инженера с пятилетним опытом написания кода читать документацию нужно 80-160 часов тренингов. Писать спецификации он после этого будет плохо, а вот читать вполне сможет.

Оставьте комментарий

Вы должны войти, чтобы оставить свой комментарий.