Включить ссылку на соответствующую документацию в сообщении об ошибке?

Мы создаем коммерческую библиотеку и примеры кода, которые используются внешними разработчиками. У нас есть (закрытая, доступная для зарегистрированных пользователей) документация, в которой подробно объясняется, как использовать библиотеку.

Многие из разработчиков являются новичками, поэтому встречается много элементарных ошибок.

Уместно ли включать ссылки на документацию в журнал ошибок? Каковы возможные недостатки? Я могу предвидеть некоторые, но кажется возможным преодолеть следующее

• URL-адрес документации устарел
• Ошибки конкретной версии, которые не отражены в последней документации
• Что-то еще не так, и мы тратим время разработчика, отправляя его в не относящийся к делу документ

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

[ОШИБКА] Не удалось выполнить цель org.apache.maven.plugins: maven-archetype-plugin: 1.2.3: создать (default-cli) в проекте standalone-pom: требуемый архетип не существует (com.example.library. archetypes: library-archetype-blank: 1.2.3.0) -> Пожалуйста, смотрите http://example.com/docs/setting-up-an-archetype для получения дополнительной информации и возможного устранения неполадок

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

Наконец, вы, вероятно, уже знаете первый закон компьютерной документации Нильсена: люди его не читают. Этот вывод еще более убедителен для веб-сайтов, где пользователи действительно избегают любого чтения, которое не является существенным для их задачи. Нажмите на Помощь? Никогда.

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

Гипертекстовые ссылки могут быть использованы для подключения краткого сообщения об ошибке на страницу с дополнительными справочными материалами или объяснением проблемы. (Не переусердствуйте, хотя.)

Да, наиболее определенно, НО:

• Гниение ссылок будет проблемой, в идеале генерировать ссылку динамически из известного целевого документа, но получать префикс из какой-либо формы конфигурации. Если сервер изменится, вы можете сохранить старый код действительным, обновив этот элемент конфигурации. Вы также можете сделать документ доступным локально, просто изменив этот префикс конфигурации.
• Управление версиями : в том же духе, если вы можете включить управление версиями в ссылку в некотором объеме, чтобы ссылка всегда указывала на правильную версию документации.
• Сделайте документ доступным для редактирования. Это что-то вроде сайта типа вики для вашей документации, где вы можете динамически исправлять ошибки, в идеале также позволяя пользователям комментировать прямо на странице. это облегчит вашим пользователям возможность участвовать и находить то, что им нужно, и вы получите отличную информацию, чтобы поддерживать документ в хорошем рабочем состоянии, но следите за тем, чтобы он регулярно отслеживался, и больше всего активно участвовали сами.
• Сгенерированные шаблоны позволяют вашей системе сборки генерировать базовый шаблон для документации непосредственно из аннотаций в коде. Пусть это будет просто, но это гарантирует, что каждая ссылка всегда будет указывать на действительную документацию. Если вы используете вики, убедитесь, что вы легко можете использовать эти шаблоны, и убедитесь, что вы можете продвигать сайт документации так же, как вы делаете для своего кода (есть сайт разработчика, который отличается от сайта prod, и продвижение кода в prod будет выполнить вставки в сайт продукта автоматически).

Если вы разрабатываете с использованием Java или .NET, документ может быть включен в файл jar или файл DLL, и, изменив префикс, ваш код может вместо этого получить его локально.

Если вы выбираете вики-подход, я настоятельно рекомендую DokuWiki за его простоту и потому, что он основан на плоских текстовых файлах, что делает его очень удобным для автоматического внедрения из системы сборки. Тем не менее, я не знаю достаточно о вашей среде или клиентах, чтобы действительно знать, подойдет ли это YMMV.

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

Этот подход был несколько проще, но и более ограниченным. Однако было положительным моментом, что документация будет всегда присутствовать, когда необходимость в ссылках не будет возможна.

Ваш подход - это следующая эволюция. Гораздо сложнее, но также имеет гораздо больше потенциальных доходов. Это будет дорого, хотя, если все сделано правильно, легко окупится.

Следует отдавать предпочтение указанию на автономную документацию, прилагаемую к библиотеке, а не на онлайн.

(com.example.library.archetypes: library-archetype-blank: 1.2.3.0) -> Пожалуйста, см. /usr/share/myprog-3.8.1/docs/setting-up-an-archetype для получения дополнительной информации и возможных неполадок.

(очевидно, если это библиотека Windows, путь будет другим).

Преимущества здесь:

• Таким образом, документация всегда синхронизируется с библиотекой. Люди разрабатывают и устраняют неисправности старых версий библиотеки. И ваша компания может изменить свое название, изменить название продукта, или кто-то может отказаться от обновления example.com.

• Сеть быстро меняется. Ссылка, которую вы даете, есть http, но через несколько лет ее основные браузеры будут поддерживать только https. Или мы все можем вернуться к gopherпротоколу.

• Устранение неполадок приложения не всегда происходит в среде с доступом к Интернету (или, по крайней мере, прямым доступом к вашему домену).

• Вы упоминаете, что ваша документация находится за стеной «аутентификации». Создание учетной записи на веб-сайте просто для того, чтобы понять сообщение об ошибке, не очень приятно (именно поэтому SO не требует, чтобы люди входили в систему).

Существует действительно успешный способ решения этой проблемы. Убедитесь, что исключение, объединенное с сообщением, достаточно уникально, чтобы при вставке его в веб-поиск можно было легко найти все соответствующие сообщения именно об этой проблеме.

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

Да, я хотел бы иметь возможность искать их. О, конечно, я знаю, что это произошло, потому что что-то осталось нулевым, а затем использовалось. Однако не всегда сразу видно, ПОЧЕМУ что-то осталось нулевым.

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

Милая пожалуйста?