Наилучшая практика написания документов многократного использования

Question

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

Нынешняя ситуация заключается в том, что (внутренняя и внешняя) документация распространяется по различным местам: Wiki, Adobe Indesign файлы, документы, текстовые файлы, встроенная документация в коде, справочные тексты в веб-интерфейсе наших продуктов и т. Д. документация написана небольшой группой разработчиков, но отслеживать все изменения почти невозможно, если вы хотите обновить все остальные источники.

В общем, мы хотим предоставить следующие виды документации (отсортированные по сложности).

• Краткое руководство
• руководство пользователя
• Помощь тексты webinterface
• руководство администрации
• Учебное пособие
• Внутренняя документация (для разработчиков)

Большая часть содержания одинаково для всех руководств (общая информация), некоторые из содержимое находится только в трех последних типах, а внутренняя документация должна содержать все содержимое.

Я просмотрел некоторые инструменты, которые часто рекомендуются для stackoverflow (а именно DITA, docBook, pandoc, doxygen, Sphinx). За исключением DITA (или DITA OT) и docBook, ни один из инструментов, похоже, не фокусируется на повторно используемом контенте. Но эти два инструмента также кажутся очень сложными, а пользователь недружелюбен.

Конечно, можно было бы использовать только LaTeX и включать только те части, которые подходят для типа документации, которую вы хотите построить. Но для меня это похоже на решение проблемы.

Так что я интересно:

• Есть ли лучшая практика о том, как писать многоразовую документацию?
• Как крупные (ger) компании управляют своей документацией?
• Есть ли способ иметь всю документацию в одном месте и скомпилировать разные версии для разных целевых групп без обработки изменений вручную?

Для внутренней документации было бы неплохо включить части кода, но это не обязательно. Было бы неплохо также использовать управление версиями (git) для поддержания содержимого.

Answer 1

Похоже, вы ищете одного-поиск инструмента документации, такие как Author-It или MadCap Flare. Они позволяют писать темы один раз, а затем вставлять эти темы в несколько документов (поэтому, когда вы вносите изменения, вам нужно всего лишь сделать это на одном месте).

Они также упрощают создание нескольких выходных форматов из одного и того же содержимого, например. HTML-версию вашего руководства администратора для вашего сайта и PDF-файл для отправки с продуктом.

Наем технического автора, который поможет вам наладить работу, вероятно, является хорошей инвестицией.

Answer 2

DITA предназначен для этого и предлагает множество механизмов повторного использования, таких как keyrefs, conkeyrefs, фильтры и т. Д. Вы можете найти вступительное видео here, которое объясняет эти механизмы. Вы должны тщательно взвешивать, стоит ли полагаться на собственный инструмент/формат для вашей документации (например, использовать Author-It или MadCap или любой другой конкурирующий инструмент). Это может быть улица с односторонним движением без каких-либо пунктов возврата. Если вы хотите переключить свой набор инструментов документации, например. потому что ваш поставщик увеличивает цены или останавливает поддержку вашего инструмента, у вас есть проблема. DITA, вероятно, дороже, но это открытый стандарт.