Как мы можем упростить просмотр HTML-документации?

Резюме: я ищу способ для рецензентов совместно комментировать как можно более близкие к «встроенным» комментарии в большом HTML-проекте.

Проблема в деталях

Я работаю в команде, которая документирует большой продукт. Набор документации HTML состоит из сотен отдельных страниц (с иерархическим оглавлением боковой панели, как и следовало ожидать); PDF всего набора документов составляет более 5000 страниц.

Когда мы документируем новую функцию или вносим значительные улучшения, такие как реорганизация, мы публикуем сборку в формате HTML для проверки разработчиками, отделом контроля качества, службой поддержки, менеджером по продукту и другими авторами. Мы публикуем в этой сборке весь набор документов, а не только измененные страницы, потому что иногда контекст имеет значение. Чтобы смягчить это, мы предоставляем ссылки на конкретные темы, которые изменились. Мы фактически добавляем эти ссылки в план документации, спецификацию, которую мы подготовили ранее, описывающую предполагаемые изменения — таким образом люди могут, если они хотят, увидеть предысторию того , почему мы внесли то или иное изменение. План документации — это страница на внутренней вики.

Прямо сейчас, когда мы отправляем запрос на проверку, мы направляем людей на эту вики-страницу и просим людей оставлять свои отзывы в виде комментариев. Это позволяет всем видеть отзывы друг друга, что означает (а) меньше повторений по сравнению с отдельными ответами и (б) более раннее обнаружение разногласий между рецензентами. Но в длинных цепочках комментариев тоже может быть сложно ориентироваться, даже с использованием потоков. И людям по-прежнему приходится проделывать дополнительную работу, чтобы писать эти комментарии, потому что они должны сообщить нам, на что они реагируют. Типичные комментарии начинаются примерно так: «в разделе «Установка плагинов» описание в третьем абзаце не совсем верно, потому что…».

Этот подход работает лучше для нас, чем ответы по электронной почте или индивидуальные комментарии к PDF-файлам только по выбранным темам. (Мы сделали и то, и другое.) Есть ли способ сделать это еще проще, позволяя людям прикреплять комментарии прямо в HTML, вроде комментирования в Документах Google, но без необходимости импортировать наш большой набор документов в какой-либо другой инструмент как раз для этого? Или текущий подход — это лучшее, что мы можем сделать без дополнительной работы?

Мы хотим, чтобы людям было легко комментировать и видеть комментарии других. Планка, которую нужно побить, — это комментарии на вики-странице. Мы не заинтересованы в том, чтобы импортировать большой набор HTML-документов в какой-то другой инструмент (который людям придется изучить). Мне интересно, есть ли уже, скажем, какой-то пакет Javascript, который мы можем внедрить в эти сборки для поддержки этой цели, или какой-то другой способ достичь этой цели.

Используемые инструменты

Мы используем систему управления исходным кодом (git), при этом работа над функциями выполняется в ветках. Сборки обзора создаются из этих ветвей и являются постоянными. (Большинству наших рецензентов неудобно просматривать исходный HTML-код, иначе я бы обошла все это, заставив их просматривать необработанный исходный код в ветке.)

Мы используем Madcap Flare для создания и сборки документации. Схема Flare для источника документа представляет собой расширенный HTML; весь HTML действителен, плюс они добавляют некоторые специфичные для инструмента теги, которые используются во время сборки. На выходе обычный HTML.

Мы используем Jenkins для управления процессом сборки. В настоящее время Дженкинс вызывает скрипт, который выполняет некоторую уборку и вызывает madbuild.exe (механизм сборки Flare). Этот скрипт публикует HTML на внутреннем сервере. Таким образом, в принципе, мы могли бы модифицировать скрипт сборки, чтобы добавить что-то дополнительное в вывод только для этих сборок веток. Мы владеем сервером, поэтому при необходимости можем что-то добавлять (например, способ хранения комментариев).