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

[lohmatii]

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

[firedragon]

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

[lohmatii]

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

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

[nerazzgadannaya]

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

[stgunholy]

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

[nerazzgadannaya]

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

[lohmatii]

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

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

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

[nerazzgadannaya]

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

[skymal4ik]

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

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

[nerazzgadannaya]

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

[nick_volynkin]

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

[Me1ram]

Confluence как бы тоже не дёшево.

[nerazzgadannaya]

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

[zzz1386]

Подробно и интересно. Спасибо!

[UvaysovRI]

Jira + Bitbucket + Confluence юзали. Понравилось!