Чи погана практика додавати зовнішні посилання в документацію?

9

Часто я опиняюсь як вирішувати помилки, знаходячи відповідь на Stack Overflow. Чи погана практика додати фрагмент, чому я зробив те, що робив, а потім додати посилання на статтю чи сторінку з Інтернету?

documentation

— TruthOf42
джерело

Можливий дублікат: Чи потрібно додати нотатки MSDN або посилання стека переповнення до вихідного коду?

— гнат

FWIW Я це роблю постійно і навіть запитував, як це правильно зробити на StackExchange . Мало того, що це відповідає на ваше запитання, але деякі аргументи «за» і «проти» можна знайти там.

4

Можливий дублікат Чи добре розміщувати посилання на сайти з питань запитання у коментарях програми?

— Док Браун

Питання стосується лише посилань (добре для мене), оскільки ви також згадуєте про копіювання частин коду / відповіді. Це я б тільки зробив, щоб пояснити складний алгоритм або обробку. Структура коду та найменування повинні бути чіткими незалежно від того, де ви читаєте про рішення.

— Kwebble

14

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

— Джим Раш
джерело

3

Додавання резюме корисне з двох причин: 1) Як зазначив Джим, це допомагає читачеві зрозуміти, застаріла чи ні посилання, і 2) змушує розробника копіювати код із посилання, щоб зрозуміти, що вони копіюють. Це допомагає переконатися, що код використовується не лише тому, що "він усуває проблему".

— Маг Сі

7

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

Що ми маємо на вікі проекту?

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

Я розміщую бібліографію (посилання) на Вікі Різне . Але тільки з тих, кому я довіряю:

Переповнення стеку : позитивні голоси і добре аргументовані
Інженерія програмного забезпечення Stackexchange : позитивні голоси і добре аргументовані
MKyong.com : Мені подобається ця сторінка. Це дійсно корисно, і його підручники насправді легко дотримуватися
MDN
W3C.org
W3Schools : Його документація є інтерактивною (у більшості випадків) та зручною для користувачів.
OWASP : для посилання на проблеми, пов'язані із безпекою та вразливими місцями
Офіційні веб-сторінки: Іноді найкращі підручники або пояснення є на офіційних веб-сторінках.

Моя бібліографія посилається на резюме, введене мною, щоб переконатися, що я зрозумів, до чого я посилаюся. Я намагаюся тримати Javadoc максимально чітким. Кожне посилання в коді посилається на вікі Redmine або код випуску Redmine.

За відсутності таких інструментів, як Redmine, я виявив корисні файли Markdown корисними для цих цілей. Загалом для розробників через ці файли знаходяться в SCM і поставляється разом з кодом.

— Лаїв
джерело

1

Я погоджуюся з усім, крім довіри W3Schools.com. Ви можете знайти більшість того, що там, на MDN, який має набагато більше повноважень.

— Alternatex

1

У школах W3 довше, ніж в MDN. Я можу помилятися, але я думаю, що W3schools має більше вмісту, навчальних посібників та документації щодо веб-технологій. Незважаючи на свої проблеми, вона залишається однією з найкращих орієнтирів для початківців, оскільки її вміст стає більш зручним та інтерактивним. З іншого боку, MDN має велике співтовариство, яке підтримує його вміст. Але з нижньої сторони він ніколи не може бути неупередженим у своїй документації, оскільки має браузер для захисту. У будь-якому випадку я з вами згоден, зараз, здається, MDN має більші повноваження. якщо ви не заперечуєте, я додам посилання на свою відповідь.

— Лаїв

4

Посилання на Інтернет є дещо проблематичним, як документація, оскільки Інтернет не гарантує, що вміст, який ви бачите за ними, буде таким самим, як бачити майбутній читач документів. Якщо можливо, прагніть пов’язати лише ресурси, які малоймовірно змінитимуть.

Наприклад, коли ви посилаєтесь на Вікіпедію, вам слід посилатися явно на сьогоднішню версію, а не на загальну назву статті. Що ж, для stackexchange.com, на даний момент, мабуть, не йдеться, але питання весь час редагуються або навіть видаляються, а через п’ять років може з’явитися нова гаряча точка збору. Я б не ризикував вивісити документацію, яка має значну ділову цінність на веб-сайті, настільки зовнішньому для вашої організації.

— Кіліан Фот
джерело

"Wayback Machine - Інтернет-архів" (web.archive.org/) - хороше місце для перевірки на видалений вміст.

— Кромстер