В этой заметке я хочу рассказать о своем подходе к ведению документации как личной, так и технической документации департамента.
Проблема. Как правило, программисты своеобразно подходят к написанию документации. Обычно слышишь что-то типа «чукча не писатель, чукча – втыкатель». И ничего из этого путного не выходит. Поэтому проблему ведения качественной документации надо решать комплексно, и начинать надо с себя.
Мысли. Организация правильного ведения документации в техническом департаменте – одна из самых важных задач технического директора. Ведь кролики — это не только ценный мех документация – это не только залог хорошей взаимозаменяемости сотрудников, основа для быстрого обучения новых сотрудников, но и накопленный опыт. Причем это будет опыт не только сотрудников, но и компании в целом.
Поясню свою мысль на примере. Руководитель проекта провел проект, он каждую неделю сталкивался с проблемами, как-то решал их. Приступая к следующему аналогичному проекту, он учтет свой неудачный опыт. Но как быть, если он уйдет из компании или проект будет вести другой РМ? Накопленный опыт одного человека не станет опытом другого автоматически. Даже если попросить первого РМ-а поделиться опытом со вторым, то без документации польза от этого будет минимальна.
Ведение документации я разделил для себя на две задачи:
Рассмотрим подробнее каждый из видов документации.
Как я говорил ранее, начинать надо с себя.
Через главу департамента проходит очень большой объем информации, и держать его в голове не представляется возможным. Еще будучи программистом я выработал для себя очень простое, но эффективное правило «сделал дело – запиши что и как делал». Если начать им руководствоваться, то постепенно оно войдет в привычку. А чем больше будешь писать, тем проще, быстрее и понятнее будет получаться. Чукча тоже сначала не был писателем документации.
Изначально я собирал информацию в файлы в формате HOWTO-шек. Схожие задачи группировал по директориям. Вся информация, которая проходила через меня, заботливо складывалась по определенным директориям. Мануалы, планы-графики, технические задания, какие-то инструкции, HOWTO-шки – ничего не пропадало.
Я выделяю следующие основные цели ведения собственной документации:
Накопление опыта. Под накоплением опыта я понимаю возможность использовать ранее собранную информацию в последующих проектах или при решении аналогичных задач.
Помимо этого, если придется объяснять коллеге что и как ты делал раньше, то достаточно будет просто поделиться своими документами, а потом лишь ответить на оставшиеся вопросы.
«Историческая ретроспектива». Сбор и хранение информации дает возможность «поднять» необходимые данные в случае «разбора полетов». Например, в случае сохранения зарплатных ведомостей можно узнать, когда и какому сотруднику повышалась зарплата. А если вы храните, скажем, ключевые результаты переписки по проекту, то в случае возникновения вопросов а-ля «откуда взялся этот срок по задаче?» всегда можно быстро вытащить нужное письмо из своих закромов.
Передача дел. Целевая аудитория моих заметок – начинающие руководители групп разработки и технические директора. Сотрудники на этих должностях, как правило, наемные работники. И, ни для кого не секрет, что такие сотрудники, скорее всего, относятся к работе в компании как к некоему этапу в жизни и понимают, что не будут работать на текущем месте работы вечно. И это нормальное положение дел.
В этом контексте, я предлагаю с самого начала готовиться к передаче дел своему последователю. Я занимаюсь этим всегда с первого дня работы в компании. И делаю это не из-за того, что готов сорваться с места в любой момент, поймите меня правильно, а потому, что качественно подготовить дела к передаче можно лишь при таком подходе.
Описание рабочих процессов и сбор данных – очень кропотливый процесс, требующий очень много времени. Если вы решите заняться документированием своих функций за 1-2 месяца, отработав пару лет в компании, то почти наверняка ничего путевого не выйдет. Записи, полученные таким путем, вряд ли будут полезны вашему последователю.
Практика. Поверьте, нет ничего приятнее, чем слышать позитивные отзывы от своих бывших коллег, на которых вы оставили департамент или отдел, о том, что документация была выполнена на хорошем уровне, и что незадокументированных моментов не осталось. Лучшая похвала!
Более того, придя на новое место, у вас будут новые дела, заботы, новые проблемы. И, как правило, при смене работы достигается договоренность, что в случае каких-то вопросов старый работодатель может какое-то время звонить своему бывшему работнику, чтобы он подсказал, как решить ту или иную проблему. Поэтому если вас будут несколько раз на дню дергать со старыми проблемами, то вам будет сложно сконцентрироваться на новых задачах.
Да, звонков от старого работодателя все равно не избежать, но, как правило, при наличии качественной документации можно просто делать отсылки к тому или иному файлу или разделу накопленной документации.
Отмечу еще один важный момент, который нужно понимать. Данные, которые проходят через вас, почти наверняка делятся на общедоступные, которыми надо делиться с командой, и конфиденциальные (например, зарплатные ведомости, резюме своих подчиненных, бюджеты на год и т.д.), поэтому наличие общей документации департамента не исключает ведение личной документации. Личная документация должна быть четкой и структурированной. Это поможет как вам, так и вашим последователям.
Накапливая и систематизируя информацию, которая проходила через меня, через какое-то время я столкнулся с необходимостью делиться этой информацией со своими коллегами.
Тут ничего удивительного не скажу. Для ведения общей документации департамента лучше всего подходит одно из решений на wiki-движке.
Основная проблема, которая встанет перед вами, как заставить сотрудников писать документацию. Расскажу про несколько подходов, которые я использовал в различных компаниях:
Конечно, если и другие подходы к получению качественной документации, но я не хочу объять необъятное, а пытаюсь описать лишь собственный опыт.
Практика.
Собственный пример. Есть такой психологический момент – если заходишь в корпоративную вики и видишь там две с половиной страницы текста, то писать туда совершенно не хочется. Поэтому я предлагаю на первых парах брать на себя структурирование и заполнение вики.
Обычно я накапливаю какой-то критический объем данных, а потом начинаю его переносить из собственных закромов в общую базу данных. Информации много, сидишь и просто пишешь-пишешь-пишешь. Со структурой я сначала не сильно заморачиваюсь, но по мере увеличения базы данных начинаю группировать схожие документы в разделы.
Еще один практический совет. Если у вас плохо получается писать, то тренируйте этот навык не только на работе. Заведите себе блог, пишите туда о своих делах. Набивайте руку.
Помните, чтобы хорошо писать документацию надо писать документацию. Со временем это начнет доставлять удовольствие, а объемы проделанной работы будут вызывать уважение у коллег.
Формулирование требований к документации проекта. Если в вашей компании используется проектное ведение работ, но подхлестнуть написание документации можно сформулировав требования к проектной документации.
Например, для завершения проекта необходимо залить в общую базу знаний:
В идеале, требования к документации проекта должны быть продолжением методологии управления проектами в компании – документа, который регламентирует порядок ведения проектов в компании. Но это более широкая тема, требующая отдельной заметки.
Требования к оформлению и комментированию кода. Эти требования выделил в отдельный пункт, потому что нельзя недооценивать качество комментирования и написания кода для последующей его поддержки.
При разработке программного обеспечения я определяю несколько несложных требований к ведению внутренней документации программистами:
В совокупности с требованиями к документированию проектов это дает неплохой результат.
Отслеживанием соблюдения требований этих занимается, как правило, либо руководитель одной из групп разработки, либо выделенный ведущий разработчик.
Наем технического писателя. Если ваша компания занимается разработкой сложных программных комплексов, которые поставляются сторонним заказчикам, то, скорее всего, вы уже столкнулись с серьезными требованиями к технической документации.
Как показала практика, ни руководитель проекта, ни разработчик не в состоянии разработать действительно качественную и всеобъемлющую документацию. Тем более на английском языке. Да, мы в состоянии сами без привлечения специалистов написать краткие описания систем и инструкции пользователей, но этого бывает недостаточно.
А мой опыт реализации документации одного из проектов на аутсорсе показал, что этот путь очень рискован и требует значительных временных затрат на то, что бы получить документы приемлемого качества.
Поэтому я вижу единственный способ получения полной, качественной и красивой документации на технически сложные платформенные решения – привлечение в штат технического писателя.
При выборе технического писателя я рекомендую быть крайне требовательным и обязательно смотреть на примеры работ соискателей. Можно научить человека каким-то специфическим моментам перевода документов в нашей предметной области, но вот быть аккуратным человека не научишь, это либо есть, либо нет.
Документы, используемые при продаже решений – это лицо компании. Первое впечатление клиента о вашем продукте будет сформировано именно по качеству документации, поэтому экономить тут не стоит.
Вывод. Документирование как разрабатываемых систем, так и внутренних процессов технического департамента – сложная задача, требующая системного подхода и комплексного решения. Ни один из описанных способов не работает в отдельности, и лишь их совокупное применение может дать качественный результат.
И помните – начинать решать проблему документирования в департаменте стоит с себя. Пионер – всем ребятам пример! Такие дела.
Перейти к следующей заметке «#20. О проектировании, разработке, тестировании и технической поддержке»
