4 августа 2021 г.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

8 комментариев:

  1. True.
    Чисто зафиксировать прочтение, и согласие)

    ОтветитьУдалить
  2. Я бы к списку причин нежелания копаться в документации добавила бы еще то, что доки сложно держать в актуальном состоянии и люди это знают. То есть насколько бы красивой, понятной и структурированной ни была дока, грош ей щена если она написана 10 лет назад (утрировано) про совсем другую систему. Так что проще уточнить у человека. Заодно контакт заведется, это тоже нельзя недооценивать.

    ОтветитьУдалить
    Ответы
    1. Согласен: актуальность тоже веская причина. Мне нравится мысль, что документации не должно быть много -- пока нет возможности автоматически проверять актуальность документации, нужно тщательно выбирать, что стоит документировать.

      >Заодно контакт заведется, это тоже нельзя недооценивать.

      Ох уж мне эти любители строить социальные сети! Социальные арахниды.

      Удалить
    2. Мне кажется, тут либо автоматическая проверка, либо понятность. То есть какие-то простые случаи можно проверить (типа последняя версия не 1.45, а 21.1), но тогда их проще и подставлять автоматически.

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

      Например, для внутренних должно быть меньше "что сделано" - у человека код перед глазами, он это и так прочитать может, и больше "что хотели сделать". А для внешних важно наоборот, не ваши провалившиеся наполеоновские планы, а как подключить джарку и какая в ней входная точка. И кого будить в пять утра в понедельник, когда все сломается.
      ц
      > Ох уж мне эти любители строить социальные сети! Социальные арахниды.
      Это необходимость, к сожалению :( Рано или поздно либо что-то сломается, либо потребуется что-то нетривиальное. И тут наличие человека, у которого можно хотя бы спросить, кого спрашивать, бесценно.

      Удалить
    3. Я имею в виду BDD и подобные подходы, где тесты являются _исполнимой_ документацией -- которая проверяется автоматически. С другой стороны, например, описание размещения модулей системы можно генерировать (и обновлять) автоматически из конфигов кластера, если он управляется чем-то вроде кубера.

      Но такое (пока?) не везде можно сделать -- например, архитектурную документацию в исполнимом виде не напишешь. И, с моей точки зрения, именно эту документацию _стоит_ писать -- а сценарии использования как раз лучше постараться совместить с тестами.

      >Это необходимость, к сожалению :( Рано или поздно либо что-то сломается, либо потребуется что-то нетривиальное. И тут наличие человека, у которого можно хотя бы спросить, кого спрашивать, бесценно.

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

      Наверняка вы помните, что Google SRE рекомендуют инженерам поддержки 50% времени заниматься автоматизацией того, что им приходится делать руками. Кажется, что с документацией разумно использовать похожий подход: 50% времени изучаешь/пишешь доки, 50% времени отвечаешь на вопросы/спрашиваешь.

      Удалить
    4. > Я имею в виду BDD и подобные подходы, где тесты являются _исполнимой_ документацией -- которая проверяется автоматически.

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

      > Но такое (пока?) не везде можно сделать -- например, архитектурную документацию в исполнимом виде не напишешь. И, с моей точки зрения, именно эту документацию _стоит_ писать -- а сценарии использования как раз лучше постараться совместить с тестами.

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

      > 50% времени изучаешь/пишешь доки, 50% времени отвечаешь на вопросы/спрашиваешь.
      а в третьи 50% - работаешь :)

      Удалить
    5. >Мне кажется, что в BDD, что в TDD теряется пресловутое "зачем". И это прямое следствие декомпозиции так что баг неустранимый.

      Я не уверен. Мне кажется, в идеале, на каждое "зачем" -- должен существовать автоматизированный проверочный/приемочный тест(-ы). И если это действительно так, то совокупность таких тестов и создает, по-сути, документацию системы.

      Но тут все равно остается вопрос -- кто эти тесты пишет, достаточно ли понятные названия даны тестам, актуальны ли названия при изменении требований...

      А то типичные тесты вида testSimple, testSimple2, testComplex действительно мало отвечают на вопрос "зачем" -- в отличие от testEventIsAlwaysDeliveredOnlyOnce.

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

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

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

      Вот, например, Алексей Шипилев в JMH целый туториал оформил просто как еще один набор бенчмарков: https://github.com/openjdk/jmh/tree/master/jmh-samples/src/main/java/org/openjdk/jmh/samples

      >а в третьи 50% - работаешь :)

      Ой, да первый раз, что ли? DevSecDocOps -- 200% продуктивности за 100 козюль/месяц.

      Удалить
  3. В будущем, роботы будут читать доки как спеки и генерировать по ним код, и сверяться с ними, никогда не лениться, указывать авторам спек на конфликты требований... (прослезился)

    ОтветитьУдалить