Целевая аудитория
Я думаю, что, отвечая на этот вопрос, вы действительно должны спросить, кто должен читать эту документацию. Разработчик имеет совершенно разные потребности для пользователя или даже бизнес-аналитика.
- Как разработчик: документация, связанная с изучаемым кодом, подробности, такие как контракт интерфейса и примеры использования. Возможно некоторая документация высокого уровня, и спецификации протокола для хорошей меры.
- Как пользователь: документация, доступная через меню справки или доступный веб-сайт о том, как использовать программное обеспечение.
- Для бизнес-аналитика полезна документация, доступная в виде документов или доступного веб-сайта. Скромное количество деталей о протоколах, высокоуровневой архитектуре и вариантах использования являются лучшими.
техническое обслуживание
От того, где разместить источник этой документации, будет зависеть ваша аудитория и кто пишет для вашей аудитории.
- Есть только дом разработчиков? Поместите все в код. Это будет способствовать его обновлению. Вам нужно будет работать над культурой, которая поощряет обновления документации так же важно, как и изменения кода.
- Есть дом разработчиков и авторов документации? Разделите обязанности. Используйте ориентированные на разработчика инструменты для разработчиков, используйте инструменты авторов документации для авторов документации.
Где возможно, убедитесь, что примеры кода или варианты использования могут быть выполнены. Автоматизируйте их выполнение и внутренне помечайте сбои. Скорее всего, эти страницы плохая или плохая документация.
Кроме того, какие бы инструменты вы ни выбрали для написания своей документации, вам нужны надежные средства, чтобы связать конкретную версию документации с конкретной версией кода. Это все еще выгодно даже в счастливой облачной стране с одним вечнозеленым развертыванием.
Интеграция документации
Интеграция может потребоваться для создания некоторой документации, но обратите внимание, что только пользователь ожидает, что единственное место будет иметь доступ ко всей необходимой документации.
Бизнес-аналитик вполне доволен спецификациями API, Designs Specs и сценариями использования, которые размещаются в отдельных документах или отдельных разделах веб-сайта.
Разработчик предпочитает все, что видно из исходного кода, но весьма рад иметь пару высокоуровневых проектных документов и подробных документов спецификации протокола, внешних по отношению к коду, хотя предпочтительно в рамках одной проверки.
Ваш случай
Если честно, документация в вашей вики, вероятно, не та же самая, что и в вашей кодовой базе. Возможно, не имеет смысла объединять.
С другой стороны, интеграция двух может быть обеспечена несколькими простыми способами.
- Инструменты исходной документации (например, doxygen) могут создавать html, и вики живет на веб-сервере. Это была бы простая точка интеграции, чтобы просто обслуживать встроенную версию вместе с вики и связывать их.
- Некоторые вики-продукты позволяют вам запускать вики прямо из файла, который вы можете зарегистрировать в базе кода. Это дает простой инструмент wysiwyg, сохраняя документацию в паре с кодом.
- Другие форматы, такие как pdf, также могут быть адаптированы, но это зависит от конкретного инструмента, который вы хотите использовать. Возможно, имеет смысл собрать вашу вики в файлы уценки и передать их через doxygen (или другие инструменты). Возможно, имеет смысл отдельно отразить вики и исходный код PDF и использовать инструмент слияния PDF.
В конце дня выясните, какая система документации имеет низкие затраты на обслуживание, и поможет вам в предоставлении высококачественного продукта, как это видно из вашей аудитории разработчиков, бизнес-аналитиков и пользователей. Все, что мешает любой из этих групп, обязательно приведет к снижению качества продукции.