Да, наиболее определенно, НО:
- Гниение ссылок будет проблемой, в идеале генерировать ссылку динамически из известного целевого документа, но получать префикс из какой-либо формы конфигурации. Если сервер изменится, вы можете сохранить старый код действительным, обновив этот элемент конфигурации. Вы также можете сделать документ доступным локально, просто изменив этот префикс конфигурации.
- Управление версиями : в том же духе, если вы можете включить управление версиями в ссылку в некотором объеме, чтобы ссылка всегда указывала на правильную версию документации.
- Сделайте документ доступным для редактирования. Это что-то вроде сайта типа вики для вашей документации, где вы можете динамически исправлять ошибки, в идеале также позволяя пользователям комментировать прямо на странице. это облегчит вашим пользователям возможность участвовать и находить то, что им нужно, и вы получите отличную информацию, чтобы поддерживать документ в хорошем рабочем состоянии, но следите за тем, чтобы он регулярно отслеживался, и больше всего активно участвовали сами.
- Сгенерированные шаблоны позволяют вашей системе сборки генерировать базовый шаблон для документации непосредственно из аннотаций в коде. Пусть это будет просто, но это гарантирует, что каждая ссылка всегда будет указывать на действительную документацию. Если вы используете вики, убедитесь, что вы легко можете использовать эти шаблоны, и убедитесь, что вы можете продвигать сайт документации так же, как вы делаете для своего кода (есть сайт разработчика, который отличается от сайта prod, и продвижение кода в prod будет выполнить вставки в сайт продукта автоматически).
Если вы разрабатываете с использованием Java или .NET, документ может быть включен в файл jar или файл DLL, и, изменив префикс, ваш код может вместо этого получить его локально.
Если вы выбираете вики-подход, я настоятельно рекомендую DokuWiki за его простоту и потому, что он основан на плоских текстовых файлах, что делает его очень удобным для автоматического внедрения из системы сборки. Тем не менее, я не знаю достаточно о вашей среде или клиентах, чтобы действительно знать, подойдет ли это YMMV.
Некоторые из наиболее успешных инструментов, которые я создал, использовали аналогичный подход, когда сообщение об ошибке предназначалось для реального пользователя, который, скорее всего, выполнит задачу. Это означало, что я должен был сделать МНОЖЕСТВО перехвата и переноса исключений, чтобы убедиться, что ошибка находится на соответствующем уровне абстракции. Я также позаботился о том, чтобы каждое сообщение об ошибке содержало наиболее вероятные источники ошибок и указывало на возможные решения: «Вы забыли установить значение конфигурации xxxx?», «Убедитесь, что xxx и yyy не конфликтуют, дав им разные имена» и т. Д. Где XXX и еще много чего будет сгенерировано из контекста, где произошла ошибка.
Этот подход был несколько проще, но и более ограниченным. Однако было положительным моментом, что документация будет всегда присутствовать, когда необходимость в ссылках не будет возможна.
Ваш подход - это следующая эволюция. Гораздо сложнее, но также имеет гораздо больше потенциальных доходов. Это будет дорого, хотя, если все сделано правильно, легко окупится.