Никто не читает документацию

В комментариях к передыдущему посту я спорил с этим утверждением, но потом порефлексировал над своим собственным опытом, и передумал: нет, и правда, почти никто.

Если аккуратнее: никто не любит читать документацию, никто не любит искать ответы на свои вопросы в документации.

Сколь бы понятную и логичную документацию я не написал – скорее всего, люди сами ее не отыщут и не прочитают. Скорее всего, люди все равно будут стараться задать вопросы мне лично, если я доступен, или сделают по своему разумению, если нет.

Конечно, это демотивирует: корячишься, стараешься писать понятно, думаешь, что делаешь что-то полезное для коллег – а коллеги все равно ходят с вопросами к тебе.

Как сейчас помню: новый член команды спрашивает у меня что-то по коду. Я начинаю рассказывать, и по ходу рассказа понимаю, что все это уже формулировал, и даже записал. Смотрю в class-level javadoc – и правда, там несколько абзацев довольно подробного описания, которое с избытком покрывает заданный вопрос.

Почему человек сам не посмотрел в javadoc? Да потому что он не ожидал, что туда имеет смысл смотреть: сколько-либо полезный комментарий есть у одного класса из ста, у большинства же классов в проекте в javadoc-е только стандартная шапка @author/@since. И размер javadoc ни на что не намекает, потому что IDEA по-умолчанию текст javadoc сворачивает.

Я даже пенять ему не стал – вспомнил, что как-то раз сам свой собственный комментарий не догадался поискать, ровно по этой причине. Хотя, конечно, было обидно.

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

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

До какой-то степени эту установку можно изменить: стараться писать более понятную, полезную, практически-ориентированную, хорошо структурированную документацию, и помогать коллегам в ней ориентироваться. Это то, чему я стараюсь учиться последние годы, отсюда интерес к когнитивной психологии (What makes rule complex, etc)

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

Но фундаментально, мне кажется, эту битву не выиграть: лучше понять, простить, и иметь реалистичные ожидания.

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

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

Если дока получилась достаточно понятной и полезной, то со временем люди начнут ее использовать и без моего посредничества (этот процесс неплохо стимулируется уходом в отпуск или увольнением :). Но это произойдет сильно не сразу, и далеко не на 100% – кто-то все равно продолжит регулярно приходить ко мне с вопросами, подробнейшим образом разобранными в документации. Кто-то все равно будет делать кое-как, неправильно – а потом приходить с вопросом как все исправить.