nerazzgadannaya15 янв 2020 в 13:59

Docs as code против или вместе с Confluence? Обзор нескольких способов публикации из репозитория в Confluence

7 мин

18K

Atlassian * Python * Подготовка технической документации * Управление проектами *

+13

Комментарии 15

lohmatii 15 янв 2020 в 14:23

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

firedragon 15 янв 2020 в 14:53

Это дорого и слишком просто, дешевле нанять инженеров и создать систему которую только они могут понять (С)

lohmatii 15 янв 2020 в 14:59

С поправкой на лицензии MS Office, без которых не будет работать редактирование в браузере, это все может бесплатный SharePoint Foundation :)

С другой стороны, если рассматривать лицензии на серверные ОС и SQL Server — уже заметно дороже. Под небольшие объемы можно недорого взять облачный шарик, опять же.

nerazzgadannaya 15 янв 2020 в 15:23

Дороговато и не подходит для тех, у кого стандарт unix и требования только сервер

stgunholy 17 янв 2020 в 08:27

Confluence точно также умеет хранить и документацию и версии и потом отдавать её в вэб. Здесь разговор о том как эту документацию сгенерить и опубликовать

nerazzgadannaya 17 янв 2020 в 08:28

именно, и в таком контексте Confluence — это просто один из форматов выгрузки

lohmatii 17 янв 2020 в 14:28

Я здесь под документами имею ввиду форматы файлов, поддерживаемые MS Office. Когда у вас лежит вордовский документ документ со сложным форматированием. Вы можете его читать и редактировать как через MS Office со все функциональностью, так и через браузер — там она чуть сокращенная. При этом у вас параллельно в одно и то же время документ может править несколько аналитиков. Система сохраняет историю правок документа, позволяет их сравнивать, откатываться к предыдущим.

Тогда отпадает необходимость писать в виде языка разметки и преобразовывать это в html или что-то еще.

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

nerazzgadannaya 17 янв 2020 в 14:35

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

skymal4ik 15 янв 2020 в 15:18

Помню рассматривал sphinx как репозиторий для документации, но он поддерживал только документы до 2го уровня вложенности.

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

nerazzgadannaya 15 янв 2020 в 15:22

В текущей версии нет такого ограничения, ты можешь TOC на любой странице добавить и у нее будут свои дочерние страницы, любой глубины. Ну и через шаблоны для ХТМЛ настроить любое отображение, можно ограничить вложенность, можно нет. ну и сфинкс — не репозиторий, он только генерирует разные форматы, процессом генерации можно управлять написанием кода на питоне

nick_volynkin 16 янв 2020 в 06:18

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