nerazzgadannaya Jan 15 2020 at 16:59

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

7 min

14K

Python*Project management*Atlassian*Technical Writing*

+16

Comments 15

lohmatii Jan 15 2020 at 17:23

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

firedragon Jan 15 2020 at 17:53

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

lohmatii Jan 15 2020 at 17:59

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

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

nerazzgadannaya Jan 15 2020 at 18:23

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

stgunholy Jan 17 2020 at 11:27

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

nerazzgadannaya Jan 17 2020 at 11:28

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

lohmatii Jan 17 2020 at 17:28

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

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

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

nerazzgadannaya Jan 17 2020 at 17:35

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

skymal4ik Jan 15 2020 at 18:18

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

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

nerazzgadannaya Jan 15 2020 at 18:22

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

nick_volynkin Jan 16 2020 at 09:18

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