Перевод статьи «Big Signs That Your Documentation Stinks».
Любопытно, что запахи кода мы охотно признаем, но когда полезность нашей документации ставится под сомнение, мы это воспринимаем в штыки. Почему так? Я подумал над этим вопросом и пришел к некоторым выводам.
Когда нам говорят о беспорядке в документации, мы не то чтобы воспринимаем это как личное оскорбление. Это скорее напоминает нежелание вспоминать о старом хламе в подвале, который нужно перебрать и вывезти перед приездом тестя с тещей. Может, у вас нет тещи, но я не могу подобрать другого подходящего сравнения. Вам просто не хочется этим заниматься и вы терпеть не можете даже слышать об этом.
Я хочу сказать, что так быть не должно. И лучший способ убеждения, который мне пришел в голову, — это поговорить о признаках непорядка в документации, которые у вас, вероятно, есть. Также мы остановимся на том, как избавиться от чувства вины и начать верить в актуальность и полезность документации. Поверьте: это отличное начало!
1. Люди не доверяют документации
Вы проводите периодические внутренние опросы в вашей компании? Я настоятельно рекомендую вам это делать, но будьте предельно внимательны к тому, как вы их создаете. Если работаете в разношерстном коллективе, привлекайте людей, которые могут помочь вам сориентироваться в различных культурах. Существуют фантастические приложения SAAS, которые помогут вам эффективно собрать нужный опрос.
Обратите внимание на закатывание глаз и несмешные шутки при упоминании документации. Вроде как ничего страшного, но именно таким образом люди, стремящиеся избегать конфронтации, жалуются на документацию 🙂
Не спрашивайте в лоб: «Доверяете ли вы документации?». Вместо этого формулируйте вопросы в стиле «Я уверен, что смогу найти актуальную информацию и документацию, касающуюся моих задач. [полностью согласен … категорически не согласен]»
Как лечить. Если документация у вас ведется непрерывно, в наихудшем случае разработчик получает автоматически сгенерированное предупреждение: «Похоже, что это устарело». Такие предупреждения сигнализируют о том, что о проблеме знают, что кто-то озабочен этим вопросом. Это снижает когнитивную нагрузку на разработчика и вызывает доверие к документации.
2. Код, предназначенный для повторного использования, не используется повторно
Вы успешно преодолели все проблемы, связанные с разработкой множества абстрактных классов и интерфейсов для реализации модульной подсистемы. Вы уверены, что в будущем все это будет использоваться во множестве других модулей.
Но этого не происходит. Похоже, все просто пишут собственные классы и интерфейсы. И в этом нет ничего плохого… Если, конечно, вы уверены, что коллеги знали о возможности сделать форк вашего кода и подогнать его под свои нужды. И если не учитывать, что теперь ваши красивые интерфейсы спутаны со всевозможной бизнес-логикой, а ведь вы так хотели добиться четкого разделения задач.
Как лечить. Когда убедитесь, что новые пул-реквесты, уменьшающие покрытие вашей документации, действительно решают проблемы, ради которых сделаны, поручите кому-нибудь хотя бы просмотреть документацию. Это поможет сразу же устранить всевозможные двусмысленности.
Кроме того, если документация создается автоматически, становится проще вести список тем, по которым люди могут найти информацию. Если вы просто скажете вашей команде: «вот модуль, используйте его повторно при необходимости», они забудут об этом через пару месяцев. В этом деле лучше положиться на документацию.
3. Новички в команде не имеют доступа к нужным сведениям
Отвечая на вопрос, начинающийся с «У тебя есть минутка?», часто ли вы чувствуете необходимость провести короткий урок истории? Или, возможно, ваша команда потеряла больше 1-2 человек всего за несколько месяцев?
Каждый член команды должен иметь доступ ко всей необходимой информации, чтобы уровень знаний о проекте был примерно одинаковым. Но велика вероятность, что значительная часть этих сведений находится в вашей голове и больше нигде.
Люди, приходящие в новый коллектив, чувствуют себя довольно уязвимыми. Они многого не знают, а вот вопросы задают куда реже, чем могли бы в более привычной обстановке. Кроме того, некоторым людям труднее заводить приятелей и находить потенциальных наставников, чем другим. Чем больше вещей будут доступными для самостоятельного изучения, тем более инклюзивной будет ваша команда.
Когда у людей возникает ощущение «я просто это не понимаю», многие считают себя виноватыми в этом, и иногда это может привести к проявлению синдрома самозванца. Но не всегда, конечно. Часть разработчиков (особенно те, кто ближе к сеньорским позициям), могут подумать, что это вы недостаточно их поддерживаете.
Со сложностями онбоардинга люди сталкиваются за свою карьеру неоднократно. И мы не можем рассчитывать, что они сами ее решат (особенно, если речь о людях, которых даже в штат еще е взяли). Делу можно помочь, если вы хотя бы скажете им, что знаете о проблемах с документацией и работаете над их устранением, но результатов нужно подождать.
Как лечить. Когда люди начнут доверять эффективности документации, у них возникнет желание развивать и поддерживать ее. Это будет стимулировать их превращать свои записи, сделанные ночью на салфетке, в документацию, которой смогут пользоваться все.
И тогда, если новичок услышит, что коллеги обсуждают что-то непонятное, он не будет чувствовать себя изолированным и обделенным, не будет просто надеяться, что все «само рассосется», и эта тема больше никогда не всплывет. Он сможет просто посмотреть нужную тему в документации.
4. Непоследовательное время реагирования на инциденты
Вряд ли ваша дежурная команда состоит из людей, разбирающихся во всем коде и во всех сервисах (хотя я признаю, что в принципе это возможно). Поэтому чаще всего реагирование на инциденты — это необходимость разбираться в коде под давлением и в сжатые сроки. Возможно, даже в условиях недостатка сна.
Так стоит ли говорить о том, насколько людям важно быстро определить, что нужно в чем-то разобраться, и быстро погрузиться в темы, связанные с проблемой?
Современные каталоги сервисов очень помогают в этом. Обычно вы довольно просто можете выяснить, где находится код и кто его писал. Но это не обязательно вам поможет, потому что автор кода вполне может оказаться в отпуске.
Как лечить. Документирование того, где что находится в базе, в комплекте с хорошо поддерживаемыми руководствами по устранению неполадок, содержащими актуальные фрагменты кода, скорее всего сократит время реагирования на инциденты.
5. Не вполне оптимальный процесс ухода из компании
Я думаю, надежного способа не дать важным знаниям уйти вместе с долго проработавшим контрибьютором, просто нет. Это верно как для проприетарного программного обеспечения, так и для проектов с открытым исходным кодом.
Если ваша процедура увольнения из компании не предполагает пересмотра документации, относящейся к тем частям кода, с которыми человек работал больше всего, вероятно, вы потеряете какие-то знания. Может быть, утечка будет совсем небольшой и в долгосрочной перспективе не сможет отрицательно повлиять на вашу команду, но вы должны знать, что она будет.
Я упоминаю об этом, потому что для большинства стартапов на ранней и средней стадии это очень большая проблема.
Как лечить. Дайте возможность человеку, который придет на место ушедшего коллеги, изучать кодовую базу по существующей документации (как только она будет проверена на актуальность). Попросите увольняющегося сотрудника написать короткий тест для проверки, готов ли новый человек справляться с его обязанностями. Убедитесь, что в документации достаточно сведений для прохождения этого теста.
Правда, если ваша документация не будет в основном актуальной, вы не сможете воспользоваться этим советом. Двухнедельного периода отработки перед увольнением просто не хватит на приведение документации в порядок.
6. Неполнота документации
Что вы добавляли в свой соус Альфредо, когда готовили его в последний раз? Он тогда был чудо, как хорош. Это был укроп или новая марка пармезана?
Возможно, вы сможете припомнить, но было бы намного лучше, если бы вы записали это сразу после того, как приготовили соус. И еще сделали бы примечание о темперировании сливок и о том, насколько сильным должен быть огонь… в общем, вы поняли. Что бы вы ни писали, лучше писать по свежим следам, пока вы все это хорошо помните.
Не поймите меня неправильно — вы, наверное, и сегодня сможете приготовить этот соус. И будет вкусно. И, прежде чем к нам набегут кулинарные критики, — я знаю, что в классическом соусе Альфредо нет сливок. Но дело не в этом, а в том , что лучше бы вы сразу записали, как его делали. То же самое и с документацией кода. Пишите ее, пока увлечены созданием своего кода, и это поможет людям осознать, что этот код стоит использовать повторно.
Как лечить. Если ваша процедура непрерывной интеграции или подготовки коммита предполагает обязательную работу с документацией, это гарантирует, что она будет написана в оптимальное время, а это повышает качество. Как вы добиваетесь этого (блокирование PR или открытие issue с указанием дедлайна) — зависит от вас. Важно то, что вы это делаете.
7. Люди перестают с нетерпением ждать периодов затишья
Сколько таких спокойных дней между трудными проектами было испорчено необходимостью наверстать упущенное по части документации? А ведь в это время разработчики могли бы заняться, наконец, тем, что им нравится…
Подобные периоды в работе предназначены для рефакторинга или увлекательных исследований и разработок, а вовсе не для дополнительной непропорциональной нагрузки, связанной с написанием документации.
Как лечить. Сделайте процесс работы над документацией непрерывным, чтобы вам не приходилось тратить на нее целые спринты и циклы охлаждения. Сделав это, в периоды затишья вы сможете уделять внимание уже только полировке отдельных мест.
Заключение
Поскольку все больше крупных компаний модернизируются и начинают использовать преимущества микросервисов, нам необходимо повышать уровень нашей стратегии документирования. Мы должны целенаправленно все записывать и каталогизировать, чтобы новые разработчики, приходящие в команду, могли определить, что им нужно изучить, и легко найти нужную информацию.
Мы также должны гарантировать (правилами), что сведения, изложенные в документации, — актуальны и релевантны. Это поможет настроить людей на успех и продемонстрировать, что мы ценим их вклад.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]
