theblabs
@theblabs

Как добавить связку данных таблиц в Confluence с данными на других страницах?

Используем Confluence для документации backend сервисов. Создаем отдельные страницы с миграциями, в которых прописываем в табличной форме параметры сущностей. Далее создаем на отдельных страницах под каждый REST API метод страницы, на которых описываем какие данные сущности отправляем в REQUEST и что ожидаем в RESPONSE

ПРОБЛЕМА
При изменении данных на странице миграций в таблице, нам приходится постоянно обновлять руками данные на других страницах. И естественно мы что то упускаем, документация становится не достоверной

ЧЕГО ХОЧЕТСЯ
Сделать связку данных в таблице МИГРАЦИЙ с данными на странице, где описываем REQUEST/RESPONSE

Подскажите, как вы решаете эту задачу? Есть ли у confluence "приложение" или макрос для решения поставленной задаче?
  • Вопрос задан
  • 623 просмотра
Пригласить эксперта
Ответы на вопрос 3
oshliaer
@oshliaer
Google Products Expert
blabs, однозначного ответа, скорее всего нет. Я бы предположил, что документация должна идти к коду при разработке и от кода - при поддержке. Т.е. в конечном итоге сначала у вас есть ТЗ на которое ссылается Confluence (оставаясь точкой отправления), а потом у вас есть код с должным набором комментариев и документов в самой кодовой базе, на которые Confluence ссылается как на результат работы, а код ссылается на некоторые паблики (например, статьи дополнительных описаний).

Автоматизировать в этом месте можно до потери пульса. Тут главное не стараться ради стараний. Поэтому, если бы я выбирал, то остался с Документами Гугл на уровне вводного описания и абстракции.

Пример проблемной автоматизации. Вот эта страница https://oshliaer.github.io/qna?target=labs/apps-sc... генерируется из Документа Гугл. И все бы ничего, но только вначале это был небольшой скрипт на 5 строк в Apps Script, а теперь это приложение на Go, которое еще и контрибьютить иногда хочется. Как вообще такое получилось!? я уже сказать не могу, но то, что это были большие переоцененные надежды на Документы Гугл - факт. Т.е. вы рискуете нарваться на автоматизацию того, что вам вообще не нужно.

Я бы Jire ничего не предпочел, но добавил бы документацию REST в OpenAPI с предложениями на изменения через git с реверс ссылками на паблик, генерируемый в Confluence. Плюс такого подхода в полнейшей и тотальной уже готовой автоматизации (подкрутить пару Docker конфигов) вплоть до тестов, проверки типов и кросс-ссылок. Обратите внимание, что ссылки должны иметь общий характер. Или же необходимо просто встроить файлы репозитория в нужный контекст статьи.

Применимо ли это к вашим задачам миграции - это отдельный вопрос. Возможно, там какие-то невероятные многоходовки, которые просто невозможно указать в комментариях в коде OpenAPI. Тогда тут нужен более системный подход. Возможно, хранение и связывание большого количества параметров через Гугл Таблицы (используя их как первоисточник) будет как-то оправдано.
Ответ написан
Комментировать
@Arty_Fact
Обратите внимание на макрос Table Filter and Charts for Confluence, у него есть возможность собирать таблицы с разных страниц.
Ответ написан
Комментировать
theblabs
@theblabs Автор вопроса
Официальный ответ от службы поддержки

I recommend having a look at the Page Properties and Page Properties Report macros in Confluence. They allow you to create a small table on a page with key and value pairs, which you can report in a larger table using the Report macro. You can watch the videos below by StiltSoft on how that works:

Reports in Confluence (3 Parts): Page Properties a...

Alternatively, that same vendor offers an app on Marketplace that would allow you to include table excerpts. See Table Filter and Charts for Confluence. Read through their documentation to see how that app works: How to use Table Excerpt and Table Include Macros.
Ответ написан
Комментировать
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Войти через центр авторизации
Похожие вопросы