Комментарии 6
Шаблоны Confluence - это действительно супер-полезно. Правда, по личному опыту, сложнг сбалансировать шаблон так, что бы его было удобно использовать всем, кто доку пишет. Особенно, если это команда разработки.
А не могли бы поделиться, в чем именно сложность?
Предположим, что разработчик самостоятельно пишет документацию. Предположим, что в реестре потребителей документации - не только разработчики, но и другие категории пользователей. Это порождает (потенциально) несколько проблем:
1) Гораздо сложнее определиться со структурой документации. Вообще, в идеале, дока должна быть хорошо профилирована, но если потребителей много и у каждой категории свои требования к качеству (содержание, в том числе) - приходится плясать на углях.
2) Если шаблон сделать достаточно детальным - им никто не будет пользоваться (чаще всего разрабы не любят писать документацию). А если сделать шаблон лаконичным - легко скатиться в неинформативность.
На примере фичи поделюсь как у нас сейчас сделано)
Есть корневая страница, на которой довольно верхнеуровневое описание и ссылки на все задачи и артефакты. Дочерними страницами лежат страницы по технической реализации, исследования, аналитика, митинг-ноутсы и всё остальное про фичу.
В итоге страницы получаются более легковестными и ориентированными на более конкретного пользователя.
Мы тут также используем вставку страницы и блоков, например, в случае с исследованиями - мастер-страница лежит в разделе со всеми исследованиями, а в фиче в дочерней странице лежит "копия", вставленная через макрос "include page".
Мы пробовали делать всё на одной странице, запихивая это в шаблон, но нам не зашло. Делать отметки в шаблоне, что какие-то разделы в шаблоне опциональные, тоже не очень помогло.
Плюс огромные страницы очень плохо заходят сторонним командам (продажи, маркетинг, поддержка и др.), даже при наличии навигация и хорошего форматирования.
Не думаю, что есть прям единое решение, чтобы пофиксить проблемы, описанные вами) на мой взгляд основная причина в том, что мы люди и у нас ооочень разное восприятие и представление как, где и что должно быть.
Хотя очень возможно, что в скором будущем появится качественная автогенерация документации и супер-пупер персонализированный поиск :)
Я думал про переиспользование и инклюды, но команда очень часто использует контекстный поиск. Плюс, у нас 2 архитектурных (компонентных) подхода. Нужно описывать и собственно компоненты и их... логические, скажем так, объединения. Оказалось "дешевле" поддерживать странички all-in-one.
Вообще, хочется docs-and-code, автосборку и все вот это. Но учитывая много-много-многолетнюю историю с конфлю - пересесть на новые рельсы уже не выйдет. :)
А, тогда да, так может и удобней быть. Тогда, возможно, стоит над форматированием и навигацией внутри больше работать, чтобы с большой страницей было удобней работать.
Про docs-and-code - пофантазировать все-таки можно, как и поресёчить какие варианты есть и на сколько трудоёмко было бы переехать :)
Как вести внутреннюю документацию: с чего начать новичку