Встречали ли вы примеры плохой документации? Я думаю, что встречали. Более того, я уверен в том, что проектов с хорошей документацией, в целом, несравненно меньше. Почему так происходит? Ведь документация - это обложка вашего проекта. Это его упаковка. Это первое, что видит пользователь, который нашел в сети вашу библиотеку или приложение. Мне кажется, проблема кроется в ответственности. Многие разработчики, особенно в сфере web разработки, просто не до конца понимают, насколько документация может быть важна, и какие последствия могут наступить при ее отсутствии или некачественном оформлении.

Те, кто со мной работал, знают, что я достаточно ответственно отношусь к документации. Но так было не всегда. Мое отношение к документации по большей части сформировала работа по специальности. Работая в Норильском Никеле в эксплуатации АСУТП, я программировал ПЛК. “Компьютер”, под который я писал программы, представлял из себя огромную распределенную систему из кучи шкафов, датчиков, двигателей, заслонок, и других исполнительных механизмов, разнесенных по всему предприятию, а также километров кабелей, передающих разнообразные управляющие сигналы. Вся эта система, это не просто “лайки” и “репосты” на дисках, это объекты реального мира. Любая ошибка или неточность в документации могла привести к технологическим простоям, потере миллионов долларов, травмам и даже гибели людей. Стоит ли говорить о важности документации при разработке и эксплуатации такого рода систем? Я думаю, тут и так все понятно.

И что ты предлагаешь? Друзья, пишите документацию. Пишите ее качественно. Это не всегда интересно, это не всегда хочется делать, зачастую это реально скучно. Тем не менее, это очень важно. Хорошая документация может сделать ваших коллег, руководителей и пользователей счастливыми, ваш проект успешным, вас дисциплинированным, а еще рано или поздно она сможет спасти кому-то жизнь.
И, кстати, существует даже международное комьюнити людей, которых волнует качественная документация. Вот вам ссылочка: http://www.writethedocs.org/