Для чего необходимо документировать и сохранять накопленные во время проекта знания
Документация в порядке
Пост о том, зачем и как аккуратно вести проектную документацию, даже если у вас Agile. Делюсь перечнем и структурой полезных документов и рекомендациями по работе с ними.
Речь пойдет в основном о внутренних документах, которые обычно никто не просит писать, но которые на самом деле нужны команде.
Небольшое лирическое отступление про то, что меня вдохновило на написание этого текста:
Теория разбитых окон
Считаю, что принцип теории можно распространить практически на все сферы жизни человека: чистота и порядок провоцируют на созидание и продуктивность, убирают элементы хаоса и отвлекающие факторы. Однако, конечно, лучше оставлять пространство для творчества и не сковывать себя абсолютной “идеальностью”.
Зачем писать
Что писать
Сложно представить проект, на котором документация не нужна совсем. Другой вопрос, что она может быть разного формата и в разных объемах, покрывать разные аспекты системы.
Легче кому-то одному потратить пару часов на документирование, чем всей команде постоянно проверять свою память.
Необходимый минимум
На мой взгляд документы, которые важны практически на любом проекте, это:
Документ-маршрутизатор
Артефакты проектных процессов
Флоу процесса разработки, статусная модель задач, доски с беклогом, план-график проекта, список нужных контактов и пр. Наличие такой документации налаживает процесс работы и делает его более комфортным. А также сильно разгружает аналитика/менеджера/тимлида и всех, кого волнует выполнение задач и сроки.
Глоссарий
Приводит всех участников работ к одному понятийному полю. Особенно полезен там, где много специальных терминов или разночтений. На некоторых проектах достаточно всего нескольких определений, но полезно все же их зафиксировать.
Артефакты бизнес-потребности и бизнес-процесса
Концептуальная модель системы
Описание основных сущностей, верхнеуровневая функциональность и взаимодействие с другими системами.
Пример верхнеуровнего описания процесса
Классы пользователей и уровни доступа
Cценарии использования
Логика работы системы
По коду или БД не всегда получается понять смысл функционала. Например, формула расчета стоимости скорее всего задается бизнес-правилами, о которых коду ничего не известно.
Описание АПИ
Тестовые данные
Среды, учетные записи и все, что нужно, чтобы не сводить с ума тестировщика однообразными вопросами.
Ограничения/нефункциональные требования
Другие типы документов
Потребность в некоторых документах возникает вариативно, в зависимости от особенностей проекта:
Архитектура системы
Иногда необходимо детальное описание сервисов и их взаимодействия. Например, если сервисов несколько и они взаимосвязаны, или если архитектура микросервисная.
Требования к данным
UX/UI макеты и прототипы
Их лучше сразу собирать в одном известном всем месте и держать в актуальном состоянии.
С чехардой в макетах разбираться потом очень сложно. Просто представьте, что у вас хотя бы 3 экрана и у каждого хотя бы по 5 состояний. И аналитик, дизайнер и разработчики смотрят каждый в свой проект в фигме.
Описание интеграций
Протоколы интеграций, спецификации АПИ, процессы и потоки данных и всё, что необходимо для избежания недоразумений при взаимодействии с другими системами.
Безопасность
В целом параметры безопасности могут быть описаны вместе с доступами или нефункциональными требованиями, либо же наследоваться от общего контура ИТ компании. Но бывают системы с приоритетом или особым подходом к этой характеристике.
Внешняя документация
Документы для пользователей, партнеров, надзорных органов и прочие артефакты, которыми система общается с внешним миром.
Как писать
Несколько инсайтов о работе с документацией:
Не забывайте про актуальность
Стоит писать только ту документацию, которую вы сможете поддерживать в актуальном состоянии.
Удобно складывать в одно место те артефакты, которые нет возможности обработать и хорошо оформить.
Растите культуру документирования в команде
Не обязательно всё должен документировать один человек, особенно если в команде нет специальной роли для этого. Даже не технические писатели умеют складывать ссылки в нужное место, писать чек-листы, комментировать макеты и прочее.
Важно договориться, как такая документация будет поддерживаться.
Комментарии в коде не всегда спасают
Структура кода не обязана повторять структуру процесса/функционала и, тем более, бизнес- и пользовательских требований. Поэтому из кода можно понять «как» работает система, но на вопросы «зачем?», «почему?» и «как должна?» отвечает именно проектная документация.
Планируйте и декомпозируйте работу с документацией
Когда-то я бронировала в календаре последние 2 часа пятницы на составление/актуализацию документации. Принимать решения в это время опасно, к тому же эта деятельность помогает подвести итоги рабочей недели и запланировать следующую.
Закрывайте техдолг
При введении функционала в эксплуатацию важно выделить время на дооформление хвостов. Иначе не видать спокойной поддержки и доработки системы.
Понять, чего не хватает, просто: представьте, что вы приходите на этот проект сейчас, и никто из предыдущей команды с вами поговорить не может.
Больше схем и диаграмм
Поможет изучение графических нотаций и UML, практика их применения, а также замечательная книга «Говори на языке диаграмм».
Учитесь писать нехудожественные тексты
Навык написания текстов сильно ускоряет процесс документирования и повышает его качество. Рекомендую использовать https://glvrd.ru. Плюс по возможности почитать «Пиши, сокращай» и «Бизнес-копирайтинг». Так и работа быстрее пойдет, и тексты станут понятнее и приятнее.
Как итог
Но важно знать, какие есть инструменты и практики и как это делают в идеальном мире. Тогда вы поймете, на чем основывать свою работу, чтобы не изобретать велосипед и не напарываться на издревле известные грабли.
Важность документирования (ведь это не просто формальность)
Положите конец неконтролируемому накоплению информации и создайте условия для открытой коммуникации.
Просмотр тем
Ваша команда приступает к работе над совершенно новым для всех вас проектом. Кто-то вспоминает, что ваша компания успешно занималась чем-то подобным всего пару лет назад. И знаете, в чем проблема? В вашей команде нет никого, кто работал в компании в то время.
Те сотрудники ушли, а вам теперь приходится ломать голову, как восполнить пробел в знаниях. Сложно избавиться от ощущения, что вы пытаетесь с закрытыми глазами попасть дротиком в мишень.
А теперь представьте, что у вас есть ресурсы, которые могли бы помочь. Представьте, что предыдущая команда подготовила подробные документы, в которых можно найти графики и планы реализации проекта, краткие итоги совещаний, описания всех этапов процессов, наброски, дорожные карты и так далее?
В таком случае у вас была бы кладезь ценной информации, от которой вы могли бы отталкиваться. Даже если бы в итоге вы сделали что-то по-другому, по крайней мере вы бы пришли к этому осознанно, имея перед глазами чужой опыт. И этот новый проект не казался бы таким пугающим.
Это лишь один из многих примеров, подтверждающих, насколько важно документирование для вашей команды. И все же, несмотря на то что подобные стрессовые ситуации нередки, многие организации по-прежнему относятся к документированию как к необязательной формальности. Согласно опросу компании BPTrends, лишь 4 % компаний утверждают, что всегда документируют свои процессы.
Лишь 4 % компаний всегда документируют свои процессы
Это понятно. Документирование кажется просто очередным пунктом в списке задач команды. Тем не менее оно дает массу преимуществ и поэтому стоит затраченных на него времени и усилий.
Что такое внутренняя документация?
Внутренняя документация — это записи, которые ваша организация ведет и использует как основу для принятия решений, касающихся ее внутренних дел. Документировать можно практически все, от графиков до важных политик, поэтому документация невероятно разнообразна. Однако всю документацию можно разделить на три основных типа: документация команды, справочная документация и проектная документация.
Важность документирования (т. е. почему этим следует заниматься?)
Мы понимаем. У вас много дел, и вести учет решений, статусов, действий для выполнения повторяющихся заданий и т. п. не кажется особо приоритетной задачей.
В решающий момент вы поймете, как хорошо, что вы когда-то начали вести документацию. Когда внезапно не сможет выйти на работу участник команды или незнакомая инициатива поставит вас в тупик, эти записи станут несомненно ценным ресурсом.
Нужно больше аргументов, чтобы убедить команду в пользе документации? Ниже перечислен ряд основных преимуществ, которые демонстрируют важность документирования.
1. Единый достоверный источник информации экономит время и энергию
Подсчитано, что среднестатистический работник интеллектуального труда тратит примерно два с половиной часа в день на поиск необходимой ему информации. При добросовестном ведении документации вся обязательная для изучения информация о задании, проекте или команде (от учетных данных аккаунтов до пошаговых инструкций) хранится централизованно и структурированно. Не нужно больше копаться в почтовом ящике или папке с загруженными файлами, чтобы найти актуальную информацию.
С документацией не нужно отвлекаться от основной работы и часами искать сведения, учетные данные, указания и т. д. при получении задания, подготовке к новому проекту или подключении к работе другого участника команды.
Описывая свои действия, можно выявить проблемные места и перегруженные рабочие процессы, что ведет к оптимизации подходов к работе в вашей команде.
2. Документация имеет существенное значение для контроля качества и контроля процессов
Задачу можно выполнить несколькими способами, и у команды должна быть возможность выбрать тот подход к работе, который ее максимально устраивает.
Но в то же время вы хотите получать стабильно хороший результат, особенно когда дело касается того, что вы производите на регулярной основе. В результатах должна прослеживаться целостность, чтобы не казалось, что работа выполнена топорно или наобум.
Документирование способствует обмену знаниями, благодаря чему ваша команда начинает понимать, как работают процессы и как обычно выглядят готовые проекты.
С документацией на руках участникам вашей команды не придется действовать наугад, пытаясь добиться стабильных результатов в периодически повторяющихся проектах, как, например, в случае с ежемесячным отчетом или ежеквартальной презентацией. У них остается пространство для маневра, чтобы придумывать оригинальные решения, и в то же время они знают, какие обязательные требования нужно соблюсти.
3. Документация позволяет не делать одно и то же дважды
Сколько раз вы начинали новый проект, но обнаруживали, что это уже было сделано раньше? Компании, которые посредством документирования ведут реестр прошлых проектов, собирают данные исследовательской работы и фиксируют принятые решения, тратят на повторную работу гораздо меньше ценного времени, которое можно уделить чему-то еще.
Зачем заново изобретать колесо, если можно взять уже выполненную работу за основу? При наличии документации вы можете обратиться к прошлой работе и почерпнуть из нее полезную информацию, вместо того чтобы снова делать уже сделанное и получать те же результаты.
4. Упрощается процесс найма и адаптации новых сотрудников
Нелегко свыкнуться с мыслью, что сотрудники рано или поздно покидают компанию, но правда бизнеса такова, что ваша команда обязательно изменится. Какие-то ее участники уйдут, и вы возьмете под свое крыло новых.
Когда приходят новые участники команды, им, как и «старичкам», период адаптации может показаться не по зубам. И, к сожалению, по данным компании Gallup, лишь 12 % сотрудников твердо убеждено, что их организация успешно справляется с адаптацией новых сотрудников.
Участникам команды нужно дать знания и возможности, чтобы они могли добиваться наилучших результатов в своей работе, а не чувствовали, будто их бросают в пекло.
Если документированию в организации придают первостепенную важность, в распоряжении у сотрудников будут всевозможные полезные руководства, инструкции и записи, к которым они смогут обращаться по мере освоения своих новых ролей. К тому же, в этих ресурсах они смогут находить ответы на свои вопросы, и вместо того, чтобы беспокоить своих коллег по каждому вопросу или затруднению, они начнут самостоятельно разбираться в работе.
5. С единым достоверным источником информации вся команда становится умнее
В работе мы склонны относиться к своим знаниям как к валюте. Если мы знаем ответы на все вопросы, то чувствуем себя в безопасности — как будто мы самый незаменимый человек в команде. Если мы начнем делиться знаниями, наша ценность как будто бы снизится.
Поэтому неудивительно, что, как показал один опрос, 60 % сотрудников столкнулись с трудностями, пытаясь получить у коллег информацию, без которой они не могли выполнять свою работу.
Документирование способствует развитию коллективных знаний всех, с кем вы работаете. Когда обмен информацией станет обычным делом в вашей команде, повышенная прозрачность и более располагающая к совместной работе и систематизации обстановка сыграют вам на руку. Вы сможете принимать более продуманные решения, так как информация не будет храниться на жестком диске — или, что еще хуже, в голове — кого-то одного.
Документация должна стать вашим лучшим другом
Вместе вы сможете преодолеть множество серьезных препятствий в работе, начиная с непредвиденного ухода или отсутствия сотрудника и заканчивая необходимостью работать над незнакомым проектом.
Это может показаться чопорным и официальным, но, сделав документирование своей первоочередной задачей, вы и ваша команда обеспечите себе запас информации, на который вы будете опираться.
Расскажите участникам вашей команды об этих преимуществах, придумайте, как заинтересовать их в документировании всего, что только можно (может, организовать посиделки с пиццей?), и расслабьтесь. Теперь знания команды будут храниться не только в головах ее участников.
Этап подготовки проекта в теории
В данной статье рассмотрены теоретические основы важнейшего этапа в управлении проектами – именно его подготовки. Это должно быть интересно как новичкам в таком непростом деле, как менеджмент проектов, так и начинающим стартаперам, и возможно, опытным менеджерам.
Что же такое проект?
Проект – одноразовая, неповторяющаяся деятельность или совокупность действий, в результате которых за определенное время достигаются четко поставленные цели.
В определенном смысле все проекты одинаковы. У всех есть потребитель (и) и \ или покровитель (и), которые ждут от реализации проекта достижения в определенное время результатов. Проекты часто реализуются с целью создания чего-то нового или осуществления больших изменений, которые можно рассматривать как завершенный вид деятельности. Проект может возникнуть исходя из новых запросов потребителей или пользователей услуг, либо из возможности получить выгоды для организации, либо на основании новых потребностей организации.
Не существует единственно «правильного» способа управления проектом. Традиционные подходы к управлению проектами сфокусированы на технических аспектах, и влиянию людей на реализацию проекта нередко уделяется меньше внимания. Однако именно люди заказывают и поддерживают проекты, поэтому лидерство, мотивация и управление вовлеченными в проект людьми так же важны, как и использование подходящих методов планирования, контроля и мониторинга.
Часто встречающиеся недостатки в реализации проектов:
На основании своих исследований Элбейк и Томас указали 10 факторов, которые многие определяют как критические для успеха проекта (расположены в соответствии с приоритетами):
Определение границ проекта
Проект начинается с идеи и возникает с целью удовлетворения потребностей человека. Идея состоит в том, чтобы сделать что-то, что кажется необходимым. Преобразование идеи в проект начинается с понимания природы потребности как движущей силы. Поэтому потребности являются основной движущей силой проекта.
Проблемы недостаточно точного определения потребностей:
Для того, чтобы понять масштабы проекта необходимо иметь следующую информацию:
ЗС и их потребности
В зависимости от особенностей проекта многие другие группы или отдельные люди могут быть заинтересованы в нем:
После того, как установлены основные ЗС, эту информацию необходимо использовать для того, чтобы обеспечить проекту максимально возможную поддержку. Обязательно нужно проверить, как реагируют на проект люди до того, как в процессе планирования будут исключены другие варианты его реализации. Если эту возможность использовать в полной мере, то команда проекта узнает о многих потенциальных препятствиях и будет хорошо информирована о приоритетах каждой группы. Один из способов понять реакции разных ЗС является анализ их точек зрения на каждое из ключевых измерений проекта – бюджет, время и качество.
Определение предназначения и целей проекта
Предназначение проекта является широким понятием и может быть соотнесено с миссией и ценностями организации, тогда как цели проекта определяют более точно, чего стремятся достичь, реализуя проект, и каким образом можно определить его успех.
Цели должны соответствовать критериям SMART:
Поставленные цели дают возможность определить шаги, с помощью которых может быть реализовано предназначение проекта и не позволить сбиться с правильного пути; использоваться для того, чтобы убедиться, что проект хорошо вписывается в деятельность организации.
Ясность целей важна для понимания того, что должно быть сделано. Если поставлены четкие цели, то это значит, что имеется определенная система взглядов на конечный результат. На основании поставленных целей происходит структурирование проекта с тем, чтобы его можно было эффективно контролировать и управлять им. Однако иногда возникает необходимость в пересмотре целей, поскольку в процессе осуществления проекта могут возникнуть новые обстоятельства, неизвестные на стадии планирования. Поэтому цели не должны быть «каменными».
Возможности и угрозы
Исследование возможностей и угроз на начальной стадии проекта может быть важным для определения его масштаба. Постоянные обсуждения с ЗС могут выявить многие потенциальные возможности и угрозы, связанные с проектом. Управление рисками (возможными угрозами проекту) будет рассмотрено ниже.
Проверка осуществимости проекта
Затраты и выгоды для оценки проекта
Риски и ситуационное планирование
Существует несколько способов выявления риска. Это в первую очередь обсуждение проекта с ЗС и рассмотрение различных перспектив, в ходе которых отдельные ЗС могут увидеть угрозы их интересам. Очень важно оценивать риск на каждом этапе реализации проекта и планировать возможные способы уменьшения его влияний. Там, где риск можно предвидеть, необходимо разработать ситуационный план, который можно применить, если ситуация риска реализуется.
Оценка риска и анализ влияния: ключевые вопросы
Основание для действий по проекту
Документирование в разработке ПО
INTRO
Добрый день, уважаемое сообщество.
Позвольте представиться. Я бизнес-аналитик, уже десять лет работаю в области разработки заказного программного обеспечения, в последнее время совмещаю роли аналитика и руководителя проектов.
Одним из болезненных вопросов в разработке ПО всегда был и остаётся процесс документирования этой самой разработки. Вам доводилось приходить на проект, который делают уже пару лет, но, при этом, вы никак не можете с ним разобраться, потому что из документов есть одно техническое задание, да и то написано в самом начале и не отражает и половины функционала системы? Мне доводилось. И это, честно говоря, очень печальное и байтораздирающее зрелище.
Поэтому на всех своих проектах я стараюсь изначально построить процесс так, чтобы неопознанного и неописанного функционала не было, все члены команды вовремя получали актуальную информацию и вообще был мир во всём
Итак, для начала отвечу на главный вопрос: для чего всё это нужно.
Есть несколько причин.
1. Документация обеспечивает «общее пространство» проекта. Любой участник в любой момент времени может получить необходимую информацию как по конкретной задаче, так и по общему направлению работы.
2. Команда говорит «на одном языке» — ведь гораздо проще понять человека, сообщающего «об ошибке в функции, описанной в Use Case №12», чем «о стрёмном баге в той фигне, которую Вася месяц назад делал».
3. Документирование позволяет четко разграничить зоны ответственности между участниками проекта.
4. Только тщательно описанные требования могут быть проверены на полноту и непротиворечивость. «Наколенные записки» — прямой и очень быстрый путь к тому, что границы проекта расползутся резвыми тараканами, а функционал, задуманный вначале, не будет монтироваться с возникающими в процессе «хотелками» заказчика.
Для себя я выработала набор базовых правил, которые позволяют эффективно документировать, планировать и контролировать разработку в комфортных для всех участников условиях.
1. Документация не должна быть избыточной и объемной. Мы пишем документы не за-ради приятного процесса постукивания по клавишам, а для того, чтобы их использовать в работе. Избыточное количество текста – раздражает и затрудняет восприятие.
2. Вся схема документирования проекта должна быть взаимоувязанной и логичной. Если в схеме существует документ, который не связан ссылкой с каким бы то ни было другим документом, то его можно безболезненно из схемы исключить.
3. Вся оценка трудозатрат должна производиться только на основании описанных атомарных задач. Сложно оценить разработку «функционала подсистемы ввода данных», гораздо проще оценить задачи «разработка формы ввода данных марсиан» и «разработка фильтра списка марсиан». Чем мельче оцениваемый элемент – тем точнее будет агрегированная оценка.
4. Всегда необходимо формировать списки оповещения заинтересованных участников. Разработчик, узнающий о необходимости доработки за три дня до релиза – это зло и подлейшая подлость, аналитик, втихаря поменявший требования и не уведомивший всех заинтересованных участников о необходимости доработки – последняя свинья, а РП, допустивший такую ситуацию – чума, холера и неприятный человек, который не справляется со своими обязанностями.
Я предлагаю на суд уважаемого сообщества схему документирования, которая кажется мне удобной, логичной и правильной. И – да, это работает.
Итак, какие типы документов используются в схеме.
1. Техническое задание.
2. Частное техническое задание (опционально).
3. Сценарий использования (Use Case).
4. Сценарий тестирования (Test Case).
5. Отчет об ошибке (Bug Report).
6. Руководство пользователя.
7. Руководство администратора (опционально).
На рисунке ниже — схема связи между этими документами. 
Изначально, при обследовании, формируется Большое Техническое задание.
Оно включает в себя:
• словарь терминов предметной области;
• описание предметной области;
• описание ролевой системы;
• описание функциональных требований;
• описание нефункциональных требований.
Описание требований в этом документе фиксируется на «верхнем уровне», то есть мы описываем не конкретные действия, а только необходимые функции. Требования оптимально разбивать на смысловые группы по подсистемам.
Например, мы описываем подсистему «Администрирование» с функциями «Создание карточки пользователя», «Удаление карточки пользователя», «Редактирование карточки пользователя». Это требования верхнего уровня, ниже в ТЗ опускаться смысла нет.
В случае, если система большая, разумно сделать Частные технические задания на каждую подсистему.
ЧТЗ должны содержать:
• ссылку на пункт ТЗ;
• максимально подробную информацию по каждой функции;
• список UseCases для функции.
Таким образом реализуется преемственность документов, что позволяет, во-первых, унифицировать их форму, во-вторых – частично реализовать повторное использование, то есть снизить затраты времени на «писанину».
Например, мы формируем ЧТЗ на всё ту же подсистему «Администрирование». Оно будет содержать описание функции: «Создание карточки. Необходимо реализовать следующий функционал: вызов карточки посредством кнопки «Создать», интерфейс карточки, содержащий следующий набор полей, сохранение карточки посредством кнопки «Сохранить», отмену сохранения посредством кнопки «Отмена»».
Use Case
Use Case — суть вариант использования, он описывает все действия, которые пользователь может произвести, и реакцию системы на эти действия.
Каждый Use Case должен быть привязан к пункту ЧТЗ.
Наиболее оптимальным, на мой взгляд, является формат описания, включающий в себя:
• Макет экрана. Макеты можно делать и сложные, «кликабельные», но, по опыту, хватает «проволочной диаграммы», сделанной с помощью Visio или аналогичного инструмента. Если на форме предполагается использование модальных окон, то они тоже должны быть прорисованы, нижеописанные таблицы для них должны дублироваться.
• Диаграмму действий экрана, в графическом виде описывающую алгоритм работы функции.
• Таблицу с описанием полей. В строке таблицы должны располагаться следующие данные: название поля, тип поля, ограничение на ввод данных (логические проверки и т.д.), роли пользователей, которым доступно чтение/редактирование поля. Если поле расчетное – то необходимо указывать формулу для расчета значения.
• Таблицу с описанием действия кнопок экрана. В строке таблицы должны содержаться данные о названии кнопки, описание действия при клике и путях перехода, если щелчок по кнопке предполагает переход на другой экран, роли пользователей, которым доступно действие.
Также возможно небольшое общее описание функционала но, как правило, оно просто не нужно.
Test Case
Test Case, что вполне самоочевидно, должен содержать описание тестовых сценариев.
В идеале, каждый такой документ привязывается к соответствующему Use Case, но бывает так, что логично объединить несколько Use Cases в один Test Case.
Оптимальным вариантом формата описания является таблица, содержащая в одном столбце описание атомарной операции, влекущей ответное действие системы, во втором – описание правильной реакции системы. Описывать, к примеру, процесс ввода текста в текстовое поле не нужно, а вот проверку валидности данных при сохранении (щелчке по кнопке «Сохранить») – обязательно.
Bug Report
Ещё немного побуду кэпом: Bug Report возникает в процессе тестирования системы как реакция тестировщика на ошибку. Каждый документ должен обязательно ссылаться на соответствующий Test Case.
Содержать документ должен:
• скриншот возникшей ошибки;
• описание предшествующих действий. Лучше всего разработать удобный для всех шаблон такого описания – это сильно экономит время разработчикам при воспроизведении бага;
• текстовое описание самой ошибки.
Руководство пользователя/Руководство администратора
Самые занудные в написании, но, тем не менее, жизненно необходимые документы.
По сути, их формирование можно даже автоматизировать, если все Test Cases и Use Cases были написаны с должным старанием и правильно оформлены.
Я не буду подробно на них останавливаться, если вдруг тема заинтересует – расскажу о том, как их составление можно автоматизировать.