Конечному пользователю в большей степени интересна собранная версия документации, но не её исходники. Поиск по собранным HTML-кам у нас реализован на уровне CI/CD. Плюс команды "прикапывают" ссылки на сборки на странице проекта
По каждому продукту получается набор HTML-страниц. Потребности в полнотекстовом поиске нет. Но в любом случае его придётся дополнительно настраивать. Если интересуетесь, рекомендую посмотреть Antora и его расширение Lunr.
Пусть один скриншот весит 500 Кб. В проекте 50 скриншотов. Итого одна версия документации на фронт требует 25 Мб. Пусть в месяц её обновляют дважды. Получаем 50 Мб в месяц. За год 600 Мб. Гонять по сети и хранить локально пол гига картинок только по одному проекту такое себе удовольствие
Бинарники обычно тяжелее простых текстовых файлов. Поэтому их ведение в git приводит к простому раздуванию репозитория. Как следствие дополнительная нагрузка на сеть при клонировании и потребление ресурсов локальной машины для хранения.
Скорее следует говорить о комбинации подходов. В водопаде анализ, проектирование, кодинг всей системы происходят последовательно. Здесь же кодинг одной фичи идёт параллельно проектированию другой.
Отказаться от Word, безусловно, можно. Вопрос - зачем? Необходимо понять потребность.
В описанной модели трассировка выполняется на уровне задач в Jira:
Бизнес-требованию соответствует эпик.
Эпик разбивается на требования стейкхолдеров, выраженные в виде пользовательских историй. В своей формулировке пользовательская история может содержать как требования к поведению системы, так и к качеству.
Далее идут подзадачи для членов команды разработки. Что им требуется сделать для реализации пользовательской истории.
Подзадачи, в свою очередь, могут быть связаны с коммитами и пулл-реквестами.
Таким образом, можно проследить цепочку от бизнес-требования до изменения в коде или даже документации, если вы ведёте её рядом с кодом. Мы, например, ведём. Я писал об этом в статье Как мы ведём документацию рядом с кодом.
Поздравляю с заслуженным первым местом! А на Sovcombank Challenge 2021 у нас совсем незначительная разница по баллам была. Скриншот лидерборда даже остался https://habr.com/ru/company/alfa/news/t/565286/
В общих чертах наш Vision - это схема компонентов решения с описанием последовательности их взаимодействия, данных и протоколов плюс текстовое описание процесса. Схема выглядит приблизительно как в разделе "Архитектура ПО" в статье Мой краткий чек-лист по скилам системного аналитика.
Деление на саб-таски выполняется совместно членами команды разработки.
Обычно либо системный аналитик либо тестировщик занимаются выкаткой поставок в бой. Но могут быть вариации
Ещё одна из рекомендаций в случае множества стейкхолдеров - заручиться поддержкой руководителя. В случае разногласий между заинтересованными сторонами руководитель примет финальное решение, окончательное и не подлежащее обсуждению. В случае затягивания сроков руководитель простимулирует подчинённых. Проблема лишь в том, что руководители обычно очень занятые люди и едва ли могут уделять достаточно внимания всем проектам, происходящим в организации
Согласен, везде есть свои преимущества и недостатки. Однако пара редакторов в масштабах банковского ИТ - это ничто. Отдел редакторов - вопрос экономической целесообразности. Тем более, если эти люди вне команд разработки и имеют слабое представление об устройстве разрабатываемого продукта
Про поводу цели. Как написано в статье, в первую очередь, хочется обеспечить консистентность документации и кода. Ведя данные артефакты в разных системах разными специалистами это сделать сложнее, чем в случае единого инструмента.
Что касается вопроса. Пользователи документации - внутренние сотрудники Банка, в первую очередь, члены команд разработки и специалисты функционального сопровождения. Наиболее частая конфигурация в Confluence такая. Есть пространство канала (например, Альфа-Бизнес Мобайл). Внутри пространства разделы с продуктами. Потребителю документации достаточно один раз получить доступ к пространству канала, чтобы начать знакомиться с документацией по составляющим его продуктам. Каких-то проблем с получением доступов в этой части не встречал
Это неплохая практика. Однако риск неактуальности документации сохраняется, т.к. реализация не всегда в точности соответствует постановке. Плюс постановка не всегда полна.
Описанные преимущества действительно имеют место быть. Однако есть и недостатки, связанные с возрастающим TTM для новых фич, т.к. разработка полной и всеобъемлющей постановки может потребовать довольно много времени. Нужно искать баланс
Для меня ведение документации рядом с кодом - это возможность повысить шанс того, что она будет полной и актуальной. Проверка полноты и актуальности обеспечивается, как минимум, в ходе ревью документации разработчиком.
Мы как-то проводили оценку качества документации. Результаты показали, что документация рядом с кодом более актуальна, чем документация, ведущаяся в других системах.
Плюс у нас есть собственное решение по проверке актуальности документации рядом с кодом. Оно анализирует коммиты и отправляет заинтересованным сторонам нотификации о том, что документация на сервис может быть неактуальна. Возможно, об этом решении выпустим отдельную публикацию
Безусловно, скрининг можно было оставить на HR и по-прежнему "жечь" его время)
В части проверки софтов хороший поинт
Конечному пользователю в большей степени интересна собранная версия документации, но не её исходники. Поиск по собранным HTML-кам у нас реализован на уровне CI/CD. Плюс команды "прикапывают" ссылки на сборки на странице проекта
Пилоты не имели целью уйти от Confluence. Их цель - знакомство с новым инструментом, оценка его удобства для ведения документации на фронт
По каждому продукту получается набор HTML-страниц. Потребности в полнотекстовом поиске нет. Но в любом случае его придётся дополнительно настраивать. Если интересуетесь, рекомендую посмотреть Antora и его расширение Lunr.
В таком случае ваш кейс обошла проблема, описанная в статье. Поздравляю! ;)
Пусть один скриншот весит 500 Кб. В проекте 50 скриншотов. Итого одна версия документации на фронт требует 25 Мб. Пусть в месяц её обновляют дважды. Получаем 50 Мб в месяц. За год 600 Мб. Гонять по сети и хранить локально пол гига картинок только по одному проекту такое себе удовольствие
Бинарники обычно тяжелее простых текстовых файлов. Поэтому их ведение в git приводит к простому раздуванию репозитория. Как следствие дополнительная нагрузка на сеть при клонировании и потребление ресурсов локальной машины для хранения.
Схемы такого типа обычно разрабатывают в MS Visio. Помимо него ещё используется Enterprise Architect. Там формат немного другой
Скорее следует говорить о комбинации подходов. В водопаде анализ, проектирование, кодинг всей системы происходят последовательно. Здесь же кодинг одной фичи идёт параллельно проектированию другой.
Отказаться от Word, безусловно, можно. Вопрос - зачем? Необходимо понять потребность.
В описанной модели трассировка выполняется на уровне задач в Jira:
Бизнес-требованию соответствует эпик.
Эпик разбивается на требования стейкхолдеров, выраженные в виде пользовательских историй. В своей формулировке пользовательская история может содержать как требования к поведению системы, так и к качеству.
Далее идут подзадачи для членов команды разработки. Что им требуется сделать для реализации пользовательской истории.
Подзадачи, в свою очередь, могут быть связаны с коммитами и пулл-реквестами.
Таким образом, можно проследить цепочку от бизнес-требования до изменения в коде или даже документации, если вы ведёте её рядом с кодом. Мы, например, ведём. Я писал об этом в статье Как мы ведём документацию рядом с кодом.
Поздравляю с заслуженным первым местом! А на Sovcombank Challenge 2021 у нас совсем незначительная разница по баллам была. Скриншот лидерборда даже остался https://habr.com/ru/company/alfa/news/t/565286/
Верно, дизайн и спеки могут быть скорректированы после обсуждения с командой
Спасибо за вопросы! По пунктам:
В общих чертах наш Vision - это схема компонентов решения с описанием последовательности их взаимодействия, данных и протоколов плюс текстовое описание процесса. Схема выглядит приблизительно как в разделе "Архитектура ПО" в статье Мой краткий чек-лист по скилам системного аналитика.
Деление на саб-таски выполняется совместно членами команды разработки.
Обычно либо системный аналитик либо тестировщик занимаются выкаткой поставок в бой. Но могут быть вариации
Ещё одна из рекомендаций в случае множества стейкхолдеров - заручиться поддержкой руководителя. В случае разногласий между заинтересованными сторонами руководитель примет финальное решение, окончательное и не подлежащее обсуждению. В случае затягивания сроков руководитель простимулирует подчинённых. Проблема лишь в том, что руководители обычно очень занятые люди и едва ли могут уделять достаточно внимания всем проектам, происходящим в организации
Нет, таких случаев не встречал
Согласен, везде есть свои преимущества и недостатки. Однако пара редакторов в масштабах банковского ИТ - это ничто. Отдел редакторов - вопрос экономической целесообразности. Тем более, если эти люди вне команд разработки и имеют слабое представление об устройстве разрабатываемого продукта
Отвечая на первый вопрос, конфликты поможет решить система контроля версий.
Что касается второго. С описанием BPMN в формате XML не сталкивался. Однако XML - это текст. Поэтому ситуация будет аналогичной первому кейсу
Спасибо за комментарий и вопрос.
Про поводу цели. Как написано в статье, в первую очередь, хочется обеспечить консистентность документации и кода. Ведя данные артефакты в разных системах разными специалистами это сделать сложнее, чем в случае единого инструмента.
Что касается вопроса. Пользователи документации - внутренние сотрудники Банка, в первую очередь, члены команд разработки и специалисты функционального сопровождения. Наиболее частая конфигурация в Confluence такая. Есть пространство канала (например, Альфа-Бизнес Мобайл). Внутри пространства разделы с продуктами. Потребителю документации достаточно один раз получить доступ к пространству канала, чтобы начать знакомиться с документацией по составляющим его продуктам. Каких-то проблем с получением доступов в этой части не встречал
Это неплохая практика. Однако риск неактуальности документации сохраняется, т.к. реализация не всегда в точности соответствует постановке. Плюс постановка не всегда полна.
Описанные преимущества действительно имеют место быть. Однако есть и недостатки, связанные с возрастающим TTM для новых фич, т.к. разработка полной и всеобъемлющей постановки может потребовать довольно много времени. Нужно искать баланс
Хороший вопрос. Тоже им регулярно задаюсь.
Для меня ведение документации рядом с кодом - это возможность повысить шанс того, что она будет полной и актуальной. Проверка полноты и актуальности обеспечивается, как минимум, в ходе ревью документации разработчиком.
Мы как-то проводили оценку качества документации. Результаты показали, что документация рядом с кодом более актуальна, чем документация, ведущаяся в других системах.
Плюс у нас есть собственное решение по проверке актуальности документации рядом с кодом. Оно анализирует коммиты и отправляет заинтересованным сторонам нотификации о том, что документация на сервис может быть неактуальна. Возможно, об этом решении выпустим отдельную публикацию