В этом году я смог посетить MongoDB World благодаря щедрой стипендии от Mongo. Я был очень впечатлен всеми новыми функциями и разнообразием выступлений, запланированных в течение дня. Одна из панелей «Эффективные стратегии поддержки гендерного разнообразия в промышленности» заставила меня задуматься о чем-то на несколько недель после этого. Один из участников дискуссии, Эша Махариши, старший инженер-программист в Mongo, немного рассказал о том, как документация является частью создания благоприятной среды.

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

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

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

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

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

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

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