Исследование внутренней документации

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

• Улучшенное управление ожиданиями: документация, в которой отслеживаются требования, обеспечивает прозрачность объема работ для всех участников и гарантирует, что ни одно требование не будет упущено из виду.
• Повышение скорости и качества создания новых функций продукта: документация позволяет учитывать все факторы, влияющие на успех разработки, что приводит к более быстрой и качественной разработке функций.
• Расширенные возможности продаж: доступ к информации о новых функциях продукта расширяет возможности продаж и консультаций ваших клиентов, бизнес-партнеров, а также сокращает число обращений в поддержку или колл-центр.
• Сокращение количества ошибок: информация о потенциальных зависимостях в бизнес-логике или архитектурных решениях помогает уменьшить количество пропущенных сценариев, что приводит к меньшему количеству ошибок и сокращению времени разработки.
• Повышение эффективности интеграции продуктов: коллеги из других команд могут найти необходимую информацию в документации другого продукта, что упрощает процесс интеграции.
• Уменьшает критичность ухода члена команды (так называемый, bus-фактор): когда знания о продукте ограничены конкретными людьми, любое отсутствие отрицательно влияет на скорость и качество разработки.
• Более быстрая адаптация новых членов команды: хорошо задокументированный продукт позволяет новым членам команды быстро ознакомиться с продуктом и эффективно внести свой вклад.

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

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

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

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

Оценка качества документации

Критерии оценки качества системной документации определяются различными стандартами и методологиями. Некоторые из критериев оценки качества системной документации, изложенные в ISO, включают:

• Актуальность: Документация должна отражать текущее состояние системы и обновляться в соответствии с любыми изменениями.
• Полнота: документация должна быть всеобъемлющей и охватывать все аспекты системы, включая ее функциональные и нефункциональные требования, а также описания ее архитектуры и технических характеристик.
• Трассируемость: документация должна быть трассируемой, что позволяет отслеживать связи между требованиями, дизайном, кодом и тестами.
• Юзабилити: документация должна быть удобной для пользователя, включая простой поиск информации и достаточное количество примеров и инструкций.
• Последовательность: Документация должна быть последовательной и свободной от противоречий между различными разделами.
• Ясность: документация должна быть ясной и недвусмысленной, обеспечивая простоту понимания и использования.
• Стиль и формат: документация должна соответствовать определенному стилю и формату, чтобы обеспечить связность и согласованность.
• Структура: документация должна иметь четко определенную структуру, облегчающую логическую организацию информации и легкий поиск.

Другим из наиболее широко признанных подходов среди системных аналитиков является точка зрения Карла Вигерса из книги “Разработка требований к программному обеспечению”.  В ней перечисляются характеристики, какими должны обладать группы требований, а значит они могут нам помочь оценить и качество всей внутренней документации на ИТ-систему:

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

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

В результате получится 3 группы характеристик по 3 метрики в каждой.

Актуальность

Проектная документация должна отражать текущее состояние системы и обновляться в соответствии с изменениями. Чтобы оценить, актуальна ли база знаний конкретного продукта, можно посмотреть на 3 показателя:

• Всего страниц. Важно отслеживать общий объем документации. Большое количество страниц может указывать на то, что документация может стать громоздкой и трудной для навигации. С другой стороны, очень малое количество страниц может свидетельствовать о том, что документация неадекватно отражает сложности и реалии продукта. Таким образом, поддержание надлежащего баланса с точки зрения объема страниц имеет решающее значение для обеспечения ясности и полноты документации. Целевое значение, к которому стоит стремиться, зависит от разных факторов, например: сложность предметной области и, значит, системы, количество функций, количество уникальных доработок под запросы партнеров или клиентов и т.д.
• Созданные страницы и обновленные страницы (последние 3-6 месяцев). Мониторинг количества страниц внутренней документации, созданных или обновленных за последние 3-6 месяцев, важен по нескольким причинам. Небольшое количество страниц может указывать на недостаточное внимание к ведению документации, что приводит к устаревшей информации. И наоборот, чрезмерное количество страниц может свидетельствовать о неорганизованности документации, что приводит к трудностям в поиске нужной информации. В качестве ориентира можно рассматривать количество задач внутри команды, предполагая, что каждая крупная задача коррелирует с изменениями документации. Следует отслеживать эту взаимосвязь, чтобы оценить, существует ли зависимость между количеством задач и обновлениями документации.
• Старые страницы. Каждый проект уникален и может предполагать свои сроки жизни и в зависимости от этого свои критерии проверки потенциально “старых” страниц. Для примера, если проект существует 5+ лет, то можно считать потенциально устаревшими страницы, созданные до 2020 года и не просматриваемые в течение последних 12 месяцев. Все такие страницы стоит проверить на актуальность и, если они уже не отражают действительности, то перенести в архив или обновить. Наличие устаревших страниц в базе знаний может иметь несколько негативных последствий:
  • Во-первых, эти устаревшие страницы могут привести к путанице и дезинформации среди пользователей, которые полагаются на базу знаний для получения точной информации.
  • Устаревшие страницы могут содержать устаревшие процессы, процедуры или сведения о продукте, что может привести к неэффективности или даже ошибкам в работе.
  • Пользователи могут тратить ненужное время на поиск устаревших страниц только для того, чтобы понять, что информация больше не актуальна.
  • Кроме того, наличие устаревших страниц может подорвать доверие к базе знаний. Пользователи могут утратить уверенность в точности и достоверности предоставленной информации, что приведет к поиску альтернативных источников или полному обходу базы знаний.

Полнота

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

• Типовая структура пространства Confluence.  Наличие согласованной структуры в пространствах разных команд важно по нескольким причинам:
  • Простота навигации: когда пространства имеют единую структуру, пользователи могут легко находить и получать доступ к важной информации из разных команд. Это экономит время и усилия при поиске определенного контента и способствует эффективному сотрудничеству.
  • Оптимизированный обмен знаниями: согласованная структура позволяет командам более эффективно обмениваться знаниями и передовым опытом. Когда все следуют одной и той же структуре, становится легче находить и понимать общую информацию, уменьшая дублирование усилий и способствуя сотрудничеству между командами.
  • Стандартизация и согласование: согласованная структура способствует тому, чтобы команды заносили в базу знаний о системе всю необходимую информацию, охватывая как бизнес, так и технические вопросы.
  • Масштабируемость: согласованная структура способствует масштабируемости, поскольку новые команды или проекты могут легко принять и адаптировать существующую структуру без значительных переделок. Он также поддерживает будущий рост и расширение, упрощая интеграцию новых команд или согласование с существующими.
• Минимальный пакет документации. В каждой компании есть свои правила ведения проектов по созданию систем вообще и базы знаний по ним в частности. Хорошо, когда при этом существует набор шаблонов, которыми рекомендуется пользоваться. Заполнение таких предложенных шаблонов для ведения базы знаний может свидетельствовать о наличии минимально необходимого объема информации о продукте, доступной для всех заинтересованных сторон:
  • Заполнение шаблонов по всем предложенным параметрам помогает четко и ясно выразить информацию, связанную с системой. Это облегчает коммуникацию между членами команды, заказчиком и другими заинтересованными сторонами, а также обеспечивает понимание общих целей и задач проекта.
  • Каждый предложенный параметр в шаблонах имеет свою значимость и помогает документировать все важные аспекты проекта. Заполнение шаблонов полностью позволяет нам иметь полную информацию, необходимую для принятия обоснованных решений, анализа рисков и успешного управления проектом.
• Использование командами DoR (Definition of Ready = критерии готовности взять задачу в работу) & DoD (Definition of Done = критерии выполнения, завершенности работ). Использование DoR и DoD является основой процесса разработки и управления проектом. Они помогают обеспечить высокое качество работы, прозрачность и эффективность в команде, а также улучшить планирование и снизить риски. Поэтому, использование DoR и DoD является необходимым важным элементом для успешной реализации проектов:
  • Definition of Ready (DoR) приносит в проект:
    • Четкое понимание требований: DoR определяет, что необходимо сделать перед тем, как посчитать, что задача готова для реализации командой разработки. Это включает четкое понимание требований, необходимых ресурсов, и любых других предварительных условий, чтобы задача могла быть успешно выполнена.
    • Эффективное планирование: DoR позволяет команде более эффективно планировать работу, так как предварительные условия и требования уже ясно определены. Это улучшает планирование и распределение ресурсов, а также помогает избежать непредвиденных задержек или проблем в процессе выполнения задачи.
    • Сокращение рисков: DoR помогает сократить риски и неопределенность, связанные с началом выполнения задачи. Задачи, отвечающие требованиям DoR, обеспечивают более ясное представление о том, что требуется для успешного выполнения работы, и уменьшают возможность непредвиденных трудностей или несоответствий.
  • Definition of Done (DoD) приносит в проект:
    • Ясность и единообразие: DoD определяет четкие критерии, которым должны соответствовать завершенные задачи или продукты. Это обеспечивает единообразие и понимание в команде о том, что считается завершенным и готовым к выпуску.
    • Качество работы: DoD помогает обеспечить высокое качество работы, поскольку определяет необходимые проверки, тестирование и другие этапы, которые должны быть выполнены перед завершением задачи. Если все критерии DoD удовлетворены, то задача считается завершенной и готовой к следующему этапу проекта.
    • Прозрачность и ответственность: DoD помогает создать прозрачность в команде и определить, когда задача может быть считаться завершенной. Это способствует более эффективному планированию и управлению проектом, а также помогает определить, кто несет ответственность за каждый этап работы.

Трассируемость

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

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

• Ссылки на задачи. Отслеживание связи между внутренней спецификацией на систему и задачами в таск-трекере способствует лучшему пониманию, учету и контролю выполнения требований, а также обеспечивает прозрачность и эффективную коммуникацию в команде. Это помогает достичь успешного завершения проекта в соответствии с требованиями и ожиданиями стейкхолдеров. Вот, что дает такая связь:
  • Учет требований: Отслеживание связи позволяет надежно учитывать все требования, описанные в спецификации системы. Каждая задача в таск-трекере может быть непосредственно связана с определенным требованием, что обеспечивает прозрачность и учет выполнения каждого требования в процессе разработки.
  • Управление изменениями: Изменения в требованиях могут возникать на протяжении всего проекта. Отслеживание связи между спецификацией на систему и задачами в таск-трекере помогает быстро и эффективно оценивать влияние изменений на уже запланированные задачи и принимать соответствующие меры для их обновления или реорганизации.
  • Прозрачность и коммуникация: Отслеживание связи между спецификацией на систему и задачами в таск-трекере способствует прозрачности и эффективной коммуникации в команде. Все участники проекта имеют четкое представление о том, какие задачи связаны с какими требованиями, и могут легко обмениваться информацией и обсуждать прогресс в достижении целей проекта.
  • Улучшение планирования и контроля: Отслеживание связи между спецификацией на систему и задачами в таск-трекере помогает улучшить планирование и контроль проекта. Руководители проекта могут легко видеть, какие задачи связаны с какими требованиями, и следить за прогрессом в реализации каждого требования.
• Компоненты. Наличие общего списка компонентов и функций продукта имеет решающее значение по нескольким причинам:
  • Согласованность: общий список гарантирует, что все команды и заинтересованные стороны находятся на одной странице в отношении компонентов и функций продукта. Эта согласованность способствует четкому пониманию и согласованности между членами команды, уменьшая путаницу и потенциальные конфликты.
  • Совместная работа и общение. Общий список способствует эффективному сотрудничеству и общению между командами, поскольку они могут легко обращаться к одному и тому же набору компонентов и функций и обсуждать их. Это общее понимание способствует более плавной координации, улучшает сотрудничество между командами и способствует эффективному принятию решений.
  • Эффективность разработки. Общий список позволяет лучше планировать и распределять задачи. Команды могут расставлять приоритеты в своей работе на основе единого понимания компонентов и функций продукта, избегая дублирования и обеспечивая оптимальное использование ресурсов. Это упрощает процесс разработки и помогает создавать более связный и хорошо интегрированный продукт.
  • Взаимодействие с клиентами. Общий список компонентов и функций позволяет командам обеспечивать согласованное и слаженное взаимодействие с пользователем или клиентом. Это гарантирует, что все части продукта работают вместе без проблем и соответствуют общему видению продукта. Это повышает удовлетворенность пользователей, уменьшает их путаницу и повышает общее качество продукта.
  • Масштабируемость и ремонтопригодность. Общий список упрощает обслуживание продукта и будущие усовершенствования. По мере развития продукта общее понимание компонентов и функций позволяет командам принимать обоснованные решения и вносить изменения, гарантируя, что продукт останется масштабируемым, адаптируемым и ремонтопригодным.
• Метки (Labels, аналог хэштегов в confluence). Использование меток в Confluence или аналогичных инструментах ведения базы знаний может быть полезным и эффективным способом организации контента и управления им. Вот несколько преимуществ и возможностей, которые предоставляют метки:
  • Поиск и фильтрация. Метки помогают быстро находить страницы или группы страниц, связанных с определенными темами, проектами, функциями или другими параметрами. Вы можете использовать метки для создания фильтров или запросов, чтобы быстро и легко найти нужную информацию.
  • Категоризация и классификация. Метки позволяют упорядочивать и классифицировать контент в Confluence. Вы можете использовать метки для группировки страниц по определенным темам, типам или объектам. Это помогает структурировать информацию и создать логическую структуру в вашем пространстве Confluence.
  • Связывание и навигация. Метки позволяют создавать ссылки и навигацию между страницами, отмеченными одинаковыми метками. Это упрощает навигацию, обеспечивает быстрый доступ к связанной информации и помогает пользователям понять контекст и связи между различными страницами.

Оформление исследования

Исследование качества ведения внутренней базы знаний. системе или продукте стоит проводить раз в 3-6 месяцев, чтобы видеть динамику (желательно, улучшение, качества работы с внутренней документацией).

Ниже есть несколько рекомендаций поэтому, как оформить результаты исследования:

• Добавьте в начало вашего исследования описание, что должно измениться к лучшему в работе компании или команды, если внутренняя база знаний будет наполняться качественнее. Желательно, чтобы эти показатели можно было измерять и смотреть в динамике.
• Добавьте комментарий к каждому критерию, который оцениваете, чтобы команды и заинтересованные стороны понимали, почему вы выбрали именно их и как они связаны с другими аспектами их работы (например, на что повлияет внедрение DoD и DoR).
• Составьте отдельные таблицы для всех 3 групп характеристик, чтобы анализ не казался слишком большим и пугающим, а оставался легко читаемым и структурирующим.

Таблица для анализа базы знаний о системе группы продуктов или проектов может выглядеть как представлено ниже с учетом рекомендаций:

1. Выделяйте цветом те значения, которые при анализе считаете хорошими (зеленым) или плохими (красным). Так можно быстрее понять общую ситуацию.
2. Добавляйте ссылки на отдельные страницы или списки, где представители команды могут быстрее найти разделы, над которыми им стоит работать.
3. Обязательно добавляйте выводы и рекомендации для каждой команды (см. правый столбец)

Актуальность

Полнота

Трассируемость

* Что можно анализировать при работе с метками разберем в отдельной статье, если это заинтересует читателей (пишите комментарии или обращайтесь к автору статьи)

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

Вывод

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