Комментарии 25
Спасибо за статью. Действительно при всех плюсах документация очень медленно переползает в исходники и действительно есть объективные причины, которые медленно преодолеваются.
Именно вопрос скриншотов нам в некоторых проектах удалось решить по-другому. Всё равно конечный продукт (back+front) собирается в CI и всё равно e2e тесты бегают. Достаточно добавить тесты, которые создают автоматические скриншоты. У нас есть требование, чтобы все окна, требующие скриншот в документации, вызывались через URL. Поэтому на выходе работает всего один простой параметризованный тест. Понятно, всё равно могут быть бинарные файлы (например, какой-нибудь мем в документации.. meme as code пока вроде не придумали), тогда да, LFS.
Вопрос ревизии MR, кстати, тоже можно решить. Достаточно на этапе сборки MR собрать выходной документ и сравнить с выходным документом предыдущей версии основной ветки. А файл сравнения уже будет содержать не текстовой diff, а diff выходного документа с картинками, форматированием, зачеркиваниями, отчеркиваниями и всем, всем, всем.
Спасибо за комментарий. Любопытный подход с генерацией скриншотов автотестами и их получением по URL.
Мы в своё время смотрели в сторону генерации фронтовой документации полностью в автоматическом режиме с использованием собственной BDD-библиотеки Akita. Но всё же не пошли в эту историю ввиду существенных ограничений в части представления информации
Спасибо за статью.
Подскажите, какие преимущества у документации рядом с кодом, если по ней потом нет кодогенерации и проверки актуальности кода документации?
Хороший вопрос. Тоже им регулярно задаюсь.
Для меня ведение документации рядом с кодом - это возможность повысить шанс того, что она будет полной и актуальной. Проверка полноты и актуальности обеспечивается, как минимум, в ходе ревью документации разработчиком.
Мы как-то проводили оценку качества документации. Результаты показали, что документация рядом с кодом более актуальна, чем документация, ведущаяся в других системах.
Плюс у нас есть собственное решение по проверке актуальности документации рядом с кодом. Оно анализирует коммиты и отправляет заинтересованным сторонам нотификации о том, что документация на сервис может быть неактуальна. Возможно, об этом решении выпустим отдельную публикацию
Хм, спасибо. На последних двух местах работы проверяют доки на полноту и актуальность через процесс: разработчик не берет в работу задачу без описания. Там же происходит и ревью.
На мой взгляд, у этого решения есть плюсы:
документация сразу наглядна и доступна всем пользователям конфы (idea не надо устанавливать, опять же))
Меньше порог входа и, кажется, время на написание документации
Сам процесс эффективный, так как он предотвращает разработку фич без анализа и без оповещения всех заинтересованных в данном куске функционала. То есть меньше риск сделать фигню и/или кого-то поломать.
Но тут, конечно, нужны определенные ценности и взгляды на разработку, у руководства в том числе. Фигак и продакшн не получится.
Это неплохая практика. Однако риск неактуальности документации сохраняется, т.к. реализация не всегда в точности соответствует постановке. Плюс постановка не всегда полна.
Описанные преимущества действительно имеют место быть. Однако есть и недостатки, связанные с возрастающим TTM для новых фич, т.к. разработка полной и всеобъемлющей постановки может потребовать довольно много времени. Нужно искать баланс
Ну кстати ТТМ, как показывает практика, в итоге при таком подходе меньше.
Так как иначе много багов и переделок.
Но допускаю, что не везде.
—
Риски неактульности сохраняются и для документации в коде, если не делать автоматических проверок. Но как писали ниже - с документацией рядом с кодом такие проверки легче внедрить.
Помимо удобного ревью разработчиком я бы назвал еще
Обновление документации может входить в definition of done
Править документацию быстрее, т.к. она лежит в том же проекте
Ну и, конечно, документация в коде сама по себе создает условия для применения процедур автоматического обеспечения/контроля актуальности.
Те же скриншоты у нас тоже сначала лежали в LFS-ной папочке. Потом, кстати, долго медитировали надо опытом Akita. И в конце родилась идея с URL. Причём родилась она сначала не для документации, а для упрощения тестирования и улучшения UX. Вообще, возник хороший принцип -- не принимать никаких архитектурных решений исключительно ради документации, но при оценке архитектурных решений учитывать критерий документируемости
Добрый день! Интересная статья, но в обозначенной проблеме я вижу один важный пробел, касающийся медленного и тяжелого развития docs as code в Вашем случае. Создается впечатление, что изначальная цель ведения документации в таком формате не обозначена. Для чего вообще требуется держать доки рядом с кодом? Я бы для начала сконцентрировался именно на вопросах необходимости переноса документации в репозитории из конфлюенс - это первый момент, который рекомендуют при начале подобных действий. Доки в гите - вещь сложная и неоднозначная. В нашей компании (Zyfra) мы осознали данную необходимость, в первую очередь, в связи с тем, что CI/CD - это наш основной процесс доставки кода клиенту, вместе с ним уходят и доки, разворачиваются в виде портала у заказчика, плюс портал развернут на наших серверах и мы можем его сделать доступным из глобальной сети. В данном случае вопрос заполненности репозиториев картинками не очень актуален, не так уж они много месте жрут. Зато есть быстрый и удобный инструмент работы с доками без необходимости выдачи доступов и т.п. танцев с бубном. Кстати, такой вопрос, а как Вы даете пользователям доки из конфлюенс? Или каждый раз при необходимости экспортируете?
Спасибо за комментарий и вопрос.
Про поводу цели. Как написано в статье, в первую очередь, хочется обеспечить консистентность документации и кода. Ведя данные артефакты в разных системах разными специалистами это сделать сложнее, чем в случае единого инструмента.
Что касается вопроса. Пользователи документации - внутренние сотрудники Банка, в первую очередь, члены команд разработки и специалисты функционального сопровождения. Наиболее частая конфигурация в Confluence такая. Есть пространство канала (например, Альфа-Бизнес Мобайл). Внутри пространства разделы с продуктами. Потребителю документации достаточно один раз получить доступ к пространству канала, чтобы начать знакомиться с документацией по составляющим его продуктам. Каких-то проблем с получением доступов в этой части не встречал
Спасибо за ответ. Но тогда как-то пропадает необходимость переноса пользовательской документации в репозитории, и вести доки для внутреннего пользования действительно удобнее в конфлюенс, и все материалы, содержащие пользовательские истории, скриншоты и т.п. проще держать во внутренней базе знаний с настроенными макросами для переиспользования, цитирования и др., а для обеспечения консистентности проще назначить пару хороших редакторов, которые будут отслеживать процессы разработки и обновления ПО. Это будет дешевле, и не надо париться над репозиториями, мердж-реквестами, черепиками и другим шаманством. Опять же, не надо дополнительно обучать сотрудников. Все-таки docs as code - это парадигма работы с внешним заказчиком и с интернет-ресурсами.
Согласен, везде есть свои преимущества и недостатки. Однако пара редакторов в масштабах банковского ИТ - это ничто. Отдел редакторов - вопрос экономической целесообразности. Тем более, если эти люди вне команд разработки и имеют слабое представление об устройстве разрабатываемого продукта
Да, согласен, конечно, "на вкус и цвет...". Я бы, со своей колокольни, порекомендовал подумать в сторону концепции документирования docs as part of development team, частью которой является docs as code, и подумать над тем, как плотнее включить писателей в процесс разработки - это к "если эти люди вне команд разработки и имеют слабое представление об устройстве разрабатываемого продукта" - просто тогда будет значительно меньше узких мест с актуализацией документации.
Спасибо за статью.
Есть пару вопросов) Если над одной частью системы работают одновременно 2 аналитика, и вносят изменения в схему PlantUML. Корректно ли потом происходит мердж или бывают ошибки рендеринга PlantUML ?
Есть ли опыт работы в BitBucket со схемами BPMN 2.0 ( в формате XML) ? Если есть, то там аналогичный вопрос про мердж.
Отвечая на первый вопрос, конфликты поможет решить система контроля версий.
Что касается второго. С описанием BPMN в формате XML не сталкивался. Однако XML - это текст. Поэтому ситуация будет аналогичной первому кейсу
Насколько я знаю, BPMN 2.0 как раз тем и примечателен, что его можно перевести в XML. Например в Camunda modeler можно посмотреть описание схемы в XML.
Что же касается первого вопроса. Я понимаю что система контроля версий может разрешить) Просто хотел узнать были ли у вас конкретно случаи, что параллельно в одну и туже схему PlantUML вносят изменения, а после слива в мастер ветку PlantUML не рендерится из за кривого мерджа ?
Вообще не понял, зачем Git LFS. Как это решает проблему бинарников? Они как занимали место, так и занимают.
Мы заливаем бинарники в гит. Ни разу нам админы гита не сказали, что ему от этого плохо стало. Причём у нас бинарники - это и картинки, и docx, и pdf. А в Альфабанке, как я понял, под ними понимают только картинки.
Бинарники обычно тяжелее простых текстовых файлов. Поэтому их ведение в git приводит к простому раздуванию репозитория. Как следствие дополнительная нагрузка на сеть при клонировании и потребление ресурсов локальной машины для хранения.
О какой нагрузке и ресурсах идёт речь? Можете привести примерные цифры?
Винта в 500 ГБ не хватает для картинок в документации? ))
Как часто техписатели и аналитики клонируют репозитории, что это грузит сеть?
По-моему, проблема слегка надумана.
Пусть один скриншот весит 500 Кб. В проекте 50 скриншотов. Итого одна версия документации на фронт требует 25 Мб. Пусть в месяц её обновляют дважды. Получаем 50 Мб в месяц. За год 600 Мб. Гонять по сети и хранить локально пол гига картинок только по одному проекту такое себе удовольствие
Взял для проверки расчётов один из самых больших наших файлов. 210 страниц. Описание веб-интерфейса с большим количеством скриншотов. Весь не проверял. Но на первых 20 страницах - 18 небольших скриншотов (части интерфейса) и 12 полноценных (где полностью экран или большая его часть). Т.е. во всём документе примерно 300 скриншотов будет.
Этот документ в docx занимает 9,3 Мб, в PDF - 7,3 Мб. А по ваших расчётам это описание занимало бы от 100 до 150 Мб (не считая текста). Так что вы как-то не так снимаете и сохраняете скриншоты.
Подскажите, на таком веб-портале документации, который у вас получается с помощью Asciidoctor, есть полнотекстовый поиск по всем страницам из коробки? Если нет, что нужно, чтобы он появился?
По каждому продукту получается набор HTML-страниц. Потребности в полнотекстовом поиске нет. Но в любом случае его придётся дополнительно настраивать. Если интересуетесь, рекомендую посмотреть Antora и его расширение Lunr.
Как мы ведём документацию рядом с кодом