Come work in Estonia – the most advanced digital society. Many Ukrainians already know that Estonia is affordable – become one of them and check out the jobs available!
×Закрыть

Зачем ИТ-специалистам тратить время на документацию

Folder image via Shutterstock.

[Об авторе: Наталия Ништа — профессиональный разработчик, воплощенный в образе миловидной барышни. Считает свою работу увлекательным хобби, делая акцент на командную игру: «Если вы меня спросите, что такое проект, — то я отвечу вам, что это люди, которые его делают. Я убеждена, что личность всегда оставляет свой отпечаток в любых вещах, которые создаёт».]

Каждый раз, когда я слышу фразу «нашему проекту столько-то (4, 5, 7...) лет», хочется спросить: «есть ли у вас документация и в каком она состоянии?».

Как показывает практика, самые типичные ситуации такие:
— Документации нет. Или руководству об этом ничего не известно.
— Документация есть. Однако руководство о ней также имеет смутное представление. Очень часто такая документация не соответствует действительности, она неполная, а местами даже лживая.
— Документация есть, но позже оказывается, что она сугубо техническая.

Хотите выделиться на собеседовании? Спросите, нет ли на проекте документов, описывающих бизнес-процессы (скорее всего, нет), есть ли в команде аналитик или проджект-менеджер. А если документация таки есть, то кто занимается её ведением.

Зачем и когда это нужно

Разумеется, можно делать записи для чего угодно. Но стоит ли тратить на это драгоценное время? А если стоит, то в каких случаях?

Руководствуясь здравым смыслом, я выделяю два наиболее важных для разработчика вида документации:

— описания бизнес-процессов проекта (Business Process Documentation) — по моему глубокому убеждению, самые нужные из всех возможных. Критически важны для понимания «а что здесь вообще происходит».

— описания особенностей и тонкостей технической реализации (Technical Documentation). Критически важны для общедоступных API и проектов; здесь качество работы определяет размер будущего community проекта. Информацию по внутреннему коду стоит фиксировать только в случае крайней необходимости. Об этом рекомендую почитать в книге господина Роберта Мартина «Чистый код».

Конечно же, существует масса прочих видов документации (например, пользовательская), но это уже совсем другая история. Целью данной статьи является осветить аспекты темы, важные непосредственно для разработчика.

Итак, в каких же случаях стоит потрудиться и что должно к этому мотивировать.

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

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

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

3. Условная заменяемость. Пожалуй, это самый неочевидный и трудный для понимания пункт, в равной степени нужный компании, проекту, команде и непосредственно разработчику. Мерой осознания этого механизма вполне можно измерять свой профессионализм. Поэтому остановимся на нём подробно.

Написание документации — это процесс отчуждения интеллектуальной собственности участников проектной команды. Если такой человек покинет проект, при этом не зафиксировав свои наработки, — фактически он унесёт с собой интеллектуальную собственность компании, и в этот момент ничего уже поделать нельзя. Остаётся только надеяться, что руководство позволило этому человеку цивилизованно покинуть проект, и он изредка сможет давать свои консультации, если будет располагать достаточным временем и желанием.

У меня вызывает искреннее недоумение, почему при столь очевидной важности интеллектуальной собственности руководство очень часто понятия не имеет, что написано в документации, если она вообще есть. Нежелание вникать в особенности функционирования проекта (и бизнеса в IT-отрасли вообще) порождает соответствующее отношение со стороны разработчиков. Создание информационной базы в данном случае — лишь малая часть тех процессов, которыми следовало бы интересоваться руководителям. Если высшее руководство не проявляет интереса ни к чему, кроме продаж, то не стоит ожидать этого от рядовых сотрудников.

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

Почему это хорошо и почему к этому стоит стремиться:
— Это неплохо компенсирует риски компании при выходе участников из проекта.
— Это полезно для команды, т.к. в случае отсутствия коллегу можно подменить без ущерба для проекта.
— Это хорошо для сотрудника, т.к. значительно облегчает передачу дел последователям.
— Это плохо для «незаменимого» сотрудника, который боится потерять своё место.

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

Очень хочу сделать акцент на «условности» заменимости. Потому что нет никакой гарантии того, что человек, который будет взят на замену, будет настолько же ответственным и квалифицированным — хороший руководитель всегда понимает это. Если повезёт. По крайней мере, я всегда искренне на это надеюсь.

Кто и когда этим занимается

Документированием технической части — вполне очевидно — занимается тот, кто эти технические решения создаёт. Если техническое решение кажется элементарно простым, понятным и прозрачным — разумеется, нет смысла снабжать его лишними описаниями. Если же не все так тривиально, а вы все равно полагаетесь на свою супер-память, а ваши последователи «и так разберутся, если не дураки», — это целиком лежит на вашей совести.

Однако если системный архитектор или техлид настоятельно просит сделать «пару строк» в вики по технической реализации — стоит его послушать, если не из чувства глубокого уважения, то хотя бы из жалости. В силу своей патологической занятости вряд ли этот человек будет просить дважды, а в случае чего — голову будут снимать именно ему.

Описания бизнес-процессов очень важны сточки зрения развития продукта, и ими обычно занимаются аналитик (BA | SA) или проджект-менеджер (PM). Всё очень просто — в норме они больше всех знают о процессах внутри проекта, поэтому никто лучше них с этой работой не справится.

Итак, вы решили сменить проект. Если он уже запущен, то стоит поинтересоваться:

1. Наличием документации и её спецификой (о чём она — техническая, пользовательский help, бизнес-процессы & so on);

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

Если записей по бизнес-процессам нет, спросите о возможности их появления: вас должны интересовать перспективы развития проекта. Вы должны понимать, что чем проект крупнее и древнее, тем сложнее в нём процессы, и без вменяемой документации (желательно слоистой или модульной) очень легко утратить контроль. А это всегда приводит к одному и тому же плачевному результату. О масштабах и симптомах этой катастрофы можно почитать всё в той же книге Роберта Мартина «Чистый код».

В новом проекте стоит узнать, планируется ли ведение документации, в каком виде, кто этим будет заниматься. И вообще, побольше разузнать о том, как ваша потенциальная команда видит себе будущий процесс разработки.

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

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

Подписаться на комментарииОтписаться от комментариев Комментарии могут оставлять только пользователи с подтвержденными аккаунтами.

Так, таке розуміння приходить з досвідом, і не на одному проекті ;)

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

Чекаємо :)

дуже дякую ) Мабуть, це найважча з тем, про яку я хочу доповісти. Вже тиждень розмірковую над тим, як про це писати.

Ще дуже бажано дивитися в сторону BDD. Воно і спека, і документація, і тести, причому все несуперечливе і актуальне. І ще воно Ubiquitous Language для BA, Dev і QA.

О ведении документации в коде хорошо написано в книге Совершенный код

Ответ на этот вопрос вообще зависит от домена, он будет разным для разных програмных систем. Например, если цена ошибки высока (пишем автопилот для Боинга), вопрос о том, писать ли документацию, вообще не стоит. Надо, пишут, еще и QA на саму документацию существует. Другая крайность — если у нас социалка про котиков, наша задача прежде всего — выяснить взлетит или не взлетит, возможно не будет там никакой поддержки никогда, через два месяца мы потратим все деньги и разбежимся — так что если мы решили писать документацию, мы тратим на абсолютно ненужную теоретическую писанину драгоценное время, которое могли бы потратить на тестирование нашего бизнеса — и вот уже конкурент выпустил такую же социалку на две недели раньше нас, все пропало, зато есть красивое описание API и бизнес процессов.

В общем случае с прикладным софтом самой четкой и лаконичной спецификацией программной системы является именно сама система, так как языки программирования гораздо лучше предназначены для формального описания взаимосвязей между сущностями и процессами, чем языки человеческие. Пересказ иных пяти строчек кода может занять страничку человеческого текста. Писать длинные спеки нет особого смысла — пока напишем, как раз новый айфон выйдет с очередной киллер фичей, которая все для нас меняет. Поэтому с такими проектами, где ошибка не критична, а вероятность изменений внешних обстоятельств высока (т. е. не космические корабли, не банки, а что-то зависящее от стремительно меняющегося мира) тратить много времени на документацию не нужно, если проект будет живой — будет передача знаний «от сердца к сердцу» (а если он живым не будет, то вообще философский вопрос, стоит ли тратить на него время). Что точно всегда нужно, это коротенькая на пол-странички письменная формулировка, о том, что это за проект, и зачем кому он нужен. Чтобы не построить вместо небоскреба сеть подземных коттеджей, соединенных подземными туннелями.

Писать вообще документацию или жертвовать ею в целях экономии времени — это уже из серии анализа рисков и их компенсации. Я рассказала, почему я вижу целесообразным документацию писать — в разумных пределах. А документация ради документации — даже не хочу обсуждать это )

Хотите выделиться на собеседовании? Спросите, нет ли на проекте документов, описывающих бизнес-процессы (скорее всего, нет), есть ли в команде аналитик или проджект-менеджер. А если документация таки есть, то кто занимается её ведением.
а если на проекте есть документация, да и еще такая страшная и сложная всякие там SRS, SAD, ER, FR и куча-куча всяких моделей и диаграмок от IDEF0, activity, use case, sequence, state chart до package и deploiment , то злые дяди начнут сразу спрашивать структуру и процедуры создания... ?

Я не думаю, что на собеседовании удастся узнать сразу всё. Цель собеседования — прощупать почву, что за проект, что за люди на нём работают, какие стандарты разработки приняты на проекте. Вы прикидываете как это сочетается с вашими представлениями о девелопменте, хочется вам с этим работать или не хочется, что вы сможете от проекта взять в качестве бесценного опыта, что сможете дать, будет ли это интересно и т.д. Ваш потенциальный работодатель прикидывает, а что вы можете дать проекту, насколько вы вписываетесь в коллектив & so on. Вы выбираете, вас выбирают. Работодатель — он не страшный. Это такие же люди как и вы. Только они уже там работают, а вы ещё нет и может быть даже и не согласитесь. Они могут вам что-то предложить, вы им, а объединившись вы вместе сможете сделать что-то большее, чем каждый по отдельности.

Если злые дяди начнут спрашивать что-то, чего вы не знаете — ну ок. Один человек не может знать всего на свете из всех областей и наук. Проводить собеседование — тоже целое искусство. Если на собеседовании человека целенаправленно валить — ну его просто заклинит и всё. И вряд ли он захочет работать в такой фирме, где при первой же встрече ему дали понять, что он «чмо неграмотное ни разу». Вы же не в рабство сдаётесь. Расскажите что умеете, чего не умеете, чему хотели бы научиться. И внимательно наблюдайте за реакцией — возможно вам с этими людьми работать, и вам должно быть комфортно.

Что касается непосредственно документации — она во многом показательна, т.к. можно довольно быстро понять, как построен процесс разработки, пока вам будут о ней рассказывать. Поэтому стоит о ней спрашивать. Отношение — вам нужно узнать отношение к девелопменту как таковому. Потому что потом от вас на этой работе будут требовать в соответствии со стандартами (или их отсутствием), принятыми в данном конкретном проекте.

Подписаться на комментарии