Миф о документации, продолжение

gaperton — 18.06.2011 И самое интересное - стоит сказать про "документацию" правду, которую в глубине души и так все знают, - и это обычно провоцирует бурление говн, и поток самых невероятных высказываний.

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


По причинам своего появления в тех случаях, когда она появляется, "документацию" можно условно подразделить на несколько видов:
1) "Договор". Когда требуется удостоверится в том, что несколько людей одинаково понимают нечто действительно важное, ибо неодинаковое понимание этого людьми будет чревато неотвратимым Пиздецом. В этих случаях, документ носит более-менее официальный статус, и он нередко подписывается сторонами - что должно символизировать, что эти стороны его прочли и поняли, что там написано.

Это, например:
- Какой-нибудь договор, которого надо придерживаться, иначе всем будет больно, и обидно.
- Какой-нибудь важный факт, существование которого не худо бы закрепить, чтобы ссылаться на него в будущем. А иначе, когда и если придет Пиздец - вы никому ничего не докажете. Это, например, факты поставки товара, и выплаты денег по договорам.
- Техническое задание, или приказ, в результате которого кому-то надо что-то сделать, и будет весьма неприятно, если оно не сделано.
- Бумажка с диаграммой классов, определением сетевого протокола, или еще чем нибудь, которую вы пишете, чтобы договориться о том, как будет устроена ваша программа, которую вы собираетесь писать большой группой людей.

Список можно продолжать, но главное, думаю понятно. Функция документа в данном случае не в том, чтобы нести знание, или какую-то новую информацию читателям. Она в том, чтобы один раз удостовериться, что несколько человек понимают какую-то важную вещь одинаково. Эта проблема и решается написанием документа. На документ можно потом ссылаться, но сама проблемная ситуация уникальна, и возникает один раз – так что этот документ не обновляется.

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

Такие документы внимательно читают, и хуйню в них не пишут. Ибо те, кто пишут хуйню, либо не читают - довольно быстро подвергаются негативному естественному отбору. В силу сугубо объективных, а не выдуманных причин.

2) "Справочник". Главная функция данного типа "документа" - это некоторый публичный эталон, с которым разные люди многократно сверяются, в чем и состоит его основная функция - он является эталоном. Надо ли говорить, что такой документ крайне дорог в разработке, и кто попало его править не может? Это, например:

- Всевозможные стандарты. Начиная с IETF RFC, ISO 9001, стандарта языка С, и заканчивая вашим внутрикорпоративным стандартом кодирования и процессом внесения изменений в релиз.
- Законы и разного рода регламенты, начиная с конституции РФ, устава вооруженных сил, и заканчивая утверждением "весь код должен лежать в системе контроля версий на сервере sources".
- Орфографический словарь русского языка.
- Описание публичного API операционной системы, или библиотеки. Некоторые такие API закреплены в стандартах, например – POSIX.

Когда люди пишут такие документы? Когда они хотят добиться какой-то одинаковости, им важно одинаково донести мысль об одинаковости до людей, и сделать возможной проверку на одинаковость.

Главная задача такого документа – служить справочником. То есть – дело не в том, что информация в нем может быть новой для читателя. Главное в том, что она гарантированно правильная, и ей можно доверять.

За первыми двумя пунктами стоят объективные проблемы. Такие документы люди пишут сами, добровольно, и не «потому, что надо», а для того, чтобы решить озвученные проблемы.

Но подождите, мы еще не закончили. Если много разных других документов. Например,

3) Обучающий материал. Все мы любим хорошие учебники, правда? Ну это же здорово, открыл учебник в любое время, а там все мегапонятно и хорошо написано. Основная функция «учебника» - донесение новых знаний до читателя структурированным и системным образом.

Ну, что дает «учебник» читателю – это понятно. А вот какую именно проблему автора решает написание «учебника»? И это самый интересный вопрос, давайте рассмотрим его подробнее.

Ну, наверное - «если написать один раз, то это будет лучше, чем объяснять ее двадцать пять раз». Это распространенное заблуждение тех, кто никогда не пробовал писать учебников. И любимая отговорка тех, кто не умеет толково объяснять.

Давайте посмотрим, как это происходит в университетах – их основная задача как раз и состоит в том, чтобы вбивать знания в головы бестолковых студентов. Они этим несколько веков занимаются, и как бэ разбираются в вопросе чуть больше, чем рядовой анонимус.

Пишут-ли университетские преподаватели учебники? Безусловно. Пишут-ли они хорошие учебники? Бывает и такое, хотя и реже. Однако, освобождает ли это их от обязанности читать лекции, и вести семинарские занятия?

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

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

Почему так? Ну право слово:
1) Лекции эффективнее в плане обучения, так как позволяют получать обратную связь от студентов в реальном времени.
2) В курс лекций куда как проще внести изменения, учтя опыт их предыдущего прочтения, и отразив изменения во взглядах на предмет.
3) На подготовку к курсу лекций уходит куда меньше времени и душевных сил.

Так почему же учебники иногда все-таки пишут? Потому, что книги, в отличии от этой вашей хуйни под названием «документация к коду», которую дай бог прочтет полтора человека, дают известность в широких кругах, почет, и уважуху.

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

Разобрались? Теперь резюмируем, и вернемся к вопросу программной документации. Итак, мы выяснили, что:
- по решаемым проблемам «документы» можно условно разделить на «договор», «справочник», и «учебник», и хоть это и не полный список, но вполне достаточный для наших целей. Например – художественная литература нас сейчас не интересует.
- Документ типа «договор» пишут и читают добровольно все, или многие, ибо иначе придет Пиздец.
- «Договор» нет нужны «поддерживать в актуальном состоянии», ибо это лежит за рамками проблемы, решаемой «договором».
- Основная фишка «справочника» в том, что ему точно можно доверять, и он всегда актуален.
- «Справочники» очень дороги в создании и содержании, и нужна действительно веская причина, чтобы его создавать. Меняется справочник редко.
- Если «справочник» будет создан без веской причины, и не будет актуальным – на него все положат хуй. Кому охота читать справочники, особенно если им нельзя доверять?
- «Учебник» - это то, что все читатели любят читать, а авторы – ненавидят писать. И пишут по своей воле только в случае, если в результате маячит почет и уважуха среди большого количества пацанов, и она им зачем-то нужна.
- «Учебник» - не самый лучший способ передачи знаний (особенно – быстро меняющихся знаний), человечеству известны более эффективные способы.
- «Учебник» не обладает свойствами «справочника», а «справочник» - «учебника».
- «Справочник» это еще более хуевое средство передачи новых знаний, чем «учебник». У него другое предназначение.

И что мы в результате имеем? Все очень просто. Многие программисты, думая о рабочей документации, не разделяют ее даже на эти три типа. Им нужна документация, которая будет в ходе проекта работать вроде "договора", чтобы она оставалась актуальной как "справочник", и была при этом так же понятна, как "учебник".

Я вам говорю - "документация" это неуловимый Джо.

Первое. «Учебников», то есть – документации, доступным языком излагающей устройство вашей системы, у вас не будет никогда. Мысль, что ее может написать нихуя не понимающий в предмете «технический писатель» - как минимум забавна. Примерно, как вера в Деда Мороза, или волшебника на голубом вертолете.

Второе. Если у вас в компании нет людей, способных прочитать лекцию по вопросам архитектуры – вам уже пиздец, и никакие гипотетические «учебники» вас не спасут. А если есть – то никакие «учебники» вам не нужны.

Третье. «Справочником» в нашем случае является исходный текст программы, с комментариями в тексте, и с комментариями к коммитам в системе контроля версий. Для тех, кто не умеет читать код – для практически всех современных языков есть автоматические генераторы «справочников» из кода, вроде JavaDoc, волшебным образом решающие проблему актуальности.

Четвертое. Тексты типа «договор», которые в нашем случае отражают требования, иногда результат проектирования, и пр. – не надо пытаться превращать в документы типа «справочник», и поддерживать актуальными. Они решают совсем другую проблему. Эта идиотская затея провалится просто потому, что это нахуй никому не нужно.

И пятое, - у меня действительно хорошая новость, для тех, кто еще не в курсе. Мы живем в 21 веке. Современные трекеры ошибок и задач, такие, как Redmine и JIRA, чудесно интегрируются с почтой и системой контроля версий. Знаете, что это значит? Я объясню.

Во-первых, вся ваша переписка по задачам и ошибкам волшебным образом подошьется к описанию задачи. Вместе с приложенными документами, ага. И ее не надо будет в муках выскребать из почты и файловой системы.

Во-вторых, если вы упомянете в комментарии к коммиту вашей VCS номер задачи, то изменения в коде также автоматически привяжутся к задаче. Что это вам даст?

А то, что глядя на код (который «справочник») в режиме «annotate» (или «Blame», он иногда по разному называтеся), вы видите слева для каждой строки, каким коммитом она добавлена. Ткнув в коммит, вы видите комментарий, который объясняет, зачем она была добавлена. А еще – в это комментарии вы будете видеть ссылку на описание задачи, в результате которой она была добавлена. А в задаче – вы увидите приложенные документы (если есть) и переписку об требованиях.

И наоборот. Вот так решается в современном мире проблема «рабочей документации».

Именно поэтому, не надо заставлять программистов «документировать». Чтобы все было хорошо, достаточно делать очень простые вещи:
- Донести до программистов простую мысль, что программа пишется в первую очередь для человека, и только во-вторую – для компьютера. Из этого много чего следует, например, то, что у идентификаторов должны быть осмысленные имена, и код должен быть в первую очередь понятным.
- Обязательно вводить практику code review, чтобы код обязательно читался человеком перед коммитом. Не, это не о том, что надо всех увещевать. Достаточно запретить все коммиты, в комментариях к которым не указана фамилия проверяющего. И донести до проверяющего мысль, что он разделяет ответственность за коммит. И – обязательно ввести стандарт оформления кода, который должен проверяться на review.
- Больно пиздить за бессодержательные комментарии к коммитам, за неуказание в них номера задач в трекере и фамилии проверяющего – убивать на месте.
- Как вариант – сделать почтовую рассылку комментариев к коммитам, на которую подписать всех, и настроить VCS-хук, запрещающий коммит без валидного номера задачи в трекере. Тогда кровопролитие будет сведено к минимуму.
- Естественно, завести трекер, интегрировать его с почтой и VCS, и настроить процесс так, чтобы все общение по текущим задачам проходило через трекер.
- Если маниакальное желание документировать не пропало – завести JavaDoc/Doxigen/whatever, и проверять их комментарии на code review.
- Для конченных маньяков документации (случаются и такие) – завести вики, и они успокоятся. Следить за контентом, который они генерят, не обязательно.
- А еще вики можно использовать для информации типа “справочник”, которая реально нужна, но не генерируются автоматом из кода. Нет, это не о диаграмме, а о стандарте оформления кода. Так что польза от вики будет.

Ну и главное. Не брать на работу программистом тех, кто не в состоянии понятным образом излагать свою мысль на родном языке. Категорически. Эта работа им противопоказана.

PS:
Сонный городок в западно-американской степи.
Вдруг из салуна вываливается бухой перец, размахивая револьвером, и кричит:
— Я Неуловимый Джо! Я Неуловимый Джо!
Приезжий ковбой в изумлении спрашивает местного:
— Что, неужели правда?.. Это - Неуловимый Джо?
— А то!
— Почему ж его никто не ловит?!
— Да кому он на хуй нужен...

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

Популярные посты:

• Архив