Включити до повідомлення про помилку посилання на відповідну документацію?

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

Багато розробників є першими користувачами, тому виникає багато рудиментарних помилок.

Чи доречно включати посилання на документацію в журнал помилок? Які можливі мінуси? Я можу передбачити декілька, але здається можливим подолати наступне

• URL-адреса документації застаріла
• Помилки, характерні для версії, які не відображені в останній документації
• Щось інше не так, і ми витрачаємо час розробника, надсилаючи його на нерелевантний документ

Нижче на прикладі того, що я маю на увазі, чи корисно додати жирний текст?

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

Відповідно до цих рекомендацій щодо повідомлення про помилки та мого досвіду, люди люблять економити час, не читаючи документації чи допомоги. Помилка Googling може бути і поза ними, тому включайте посилання, коли у них є причина натискати на неї.

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

Користувачі читають системну документацію лише тоді, коли їм трапляються проблеми (це другий закон). Вони особливо уважні, коли хочуть відновитися після помилки. Враховуючи це, ви можете використовувати повідомлення про помилки як навчальний ресурс, щоб передавати незначну кількість знань користувачам. Звичайно, повідомлення про помилки мають бути короткими і точними, як і весь веб-контент. Однак повідомлення про помилки все ще можуть трохи навчити користувачів про те, як працює система, та надати їм інформацію, необхідну для кращого використання. З цією метою основна технологія Інтернету робить можливим ще один настанов:

Гіпертекстові посилання можуть використовуватися для підключення стислого повідомлення про помилку до сторінки з додатковим довідковим матеріалом або поясненням проблеми. (Не перестарайтеся з цим.)

Так, остаточно, АЛЕ:

• Гниль посилань буде проблемою, в ідеалі динамічно генеруйте посилання з відомого цільового документа, але отримуйте префікс з якоїсь форми конфігурації. Якщо сервер зміниться, ви можете зберегти старіший код дійсним, оновивши цей елемент конфігурації. Ви також можете зробити документ доступним на локальному рівні також просто змінивши цей конфігурацію префікса.
• Версія : У тому ж дусі, якщо ви можете включити версію в посилання в якійсь якості, щоб посилання завжди вказувало на правильну версію документації.
• Зробіть документ доступним для редагування Щось на зразок веб-сайту типу вікі для вашої документації, де ви можете динамічно виправляти помилки, в ідеалі також дозволяти користувачам коментувати безпосередньо на сторінці. це набагато полегшить вашим користувачам участь та пошук того, що їм потрібно, і ви отримаєте золоту інформацію про підтримку свого документа в хорошому робочому стані, але переконайтеся, що ви регулярно його стежите, і більшість з них активно берете участь самі.
• Згенеровані шаблони змушують вашу систему збирання генерувати основний шаблон для документації з приміток у коді безпосередньо. Нехай це буде просто, але це гарантуватиме, що всі посилання завжди вказують на дійсну документацію. Якщо ви користуєтесь вікі, переконайтеся, що ви можете легко пересувати ці шаблони, і переконайтеся, що ви можете просувати сайт документації так само, як і для свого коду (мати розроблений веб-сайт, який відрізняється від веб-сайту prod та рекламний код для prod буде виконати вставки на сайті prod автоматично).

Якщо ви розробляєте Java або .NET, документ може бути включений у jar-файл або файл DLL і, змінивши префікс, ваш код може отримати його локально.

Якщо ви все-таки обираєте підхід до wiki, я настійно рекомендую 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протоколу.

• Усунення несправностей із додатками не завжди відбувається в середовищі з доступом до Інтернету (або принаймні прямого доступу до вашого домену).

• Ви згадуєте, що ваша документація знаходиться за стіною "автентифікації". Необхідно створити обліковий запис на веб-сайті лише для того, щоб зрозуміти повідомлення про помилку - це не приємно (саме тому ТАК не вимагає входу людей).

Є дійсно вдалий спосіб підійти до цієї проблеми. Переконайтеся, що виняток у поєднанні з повідомленням є достатньо унікальним, що вставляючи їх у веб-пошук, можна легко знайти всі відповідні публікації про саме цю проблему.

Це таємна причина, що я так ненавиджу винятки з нульових покажчиків. Звичайно, я ненавиджу, що нам навіть доводиться перевіряти наявність нуля, але що мене найбільше турбує, це те, що коли я натрапляю на один, єдиний справді унікальний ідентифікатор, за яким я маю шукати, - це мінливий номер рядка.

Так, я хотів би мати можливість їх шукати. Ну звичайно, я знаю, що це сталося тому, що щось було залишено нульовим, а потім використане. Що не завжди відразу очевидно, хоча ЧОМУ щось було залишено нульовим.

Тож обов'язково врахуйте всі ці інші документаційні рішення. Але найголовніше, що ти можеш зробити, що зробить мені найкраще - це просто дати мені щось, що я можу гугл.

Гарненько будь ласка?