Плохо ли добавлять внешние ссылки в документацию?

9

Часто я решаю ошибки, находя ответ по переполнению стека. Это плохая практика - добавлять фрагмент того, почему я сделал то, что я сделал, а затем добавить ссылку на статью или страницу из Интернета?

documentation TruthOf42
источник
Возможный дубликат Должен ли я добавлять примечания MSDN или ссылки переполнения стека к исходному коду?
комнат
FWIW Я делаю это все время, и даже спросил, как сделать это правильно на StackExchange . Не то чтобы это отвечало на ваш вопрос, но некоторые аргументы за и против можно найти там.
4
Возможные дубликаты Можно ли размещать ссылку на сайты вопросов и ответов в комментариях программы?
Док Браун
Это вопрос только о ссылках (ОК для меня), потому что вы также упоминаете о копировании частей кода / ответа. Это то, что я хотел бы сделать, чтобы объяснить сложный алгоритм или обработку. Структура кода и наименования должны быть ясны независимо от того, где вы читаете о решении.
Квеббл

Ответы:

14

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

Джим Раш
источник
3
Добавление резюме полезно по двум причинам: 1) как указал Джим, это помогает читателю понять, устарела ли ссылка, и 2) вынуждает разработчика копировать код из ссылки, чтобы понять, что они копируют. Это помогает убедиться, что код используется не только потому, что «он решает проблему».
Маг Xy
7

Вот почему у компаний должен быть свой собственный репозиторий знаний. Например, в моей компании есть корпоративный Redmine, который используется для управления проектом, создания билетов (отслеживания ошибок и задач) и инструмента, который я использую чаще всего, вики . Все эти функции в каждом проекте :-)

Что мы имеем в вики проекта?

  • Ссылки на документацию: функциональные, технические, архитектурные, требования.
  • Вовлеченные участники: менеджер проекта, разработчики, менеджеры по работе с ключевыми клиентами, ...
  • Описание для среды: виртуальные машины, ОС, серверы, конфигурации ...
  • Разное: Любая важная / интересная вещь (связанная с проектом), изученная в течение жизни проекта.
  • Еще несколько страниц.

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

  • Переполнение стека : положительные голоса и хорошие аргументы
  • Разработка программного обеспечения Stackexchange : положительные голоса и хорошие аргументы
  • MKyong.com : Мне нравится эта страница. Это действительно полезно, и его учебники очень легко следовать
  • MDN
  • W3C.org
  • W3Schools : документация интерактивная (в большинстве случаев) и удобная для пользователя.
  • OWASP : для ссылки на вопросы, связанные с безопасностью и уязвимостями
  • Официальные веб-страницы. Иногда лучшие учебные пособия или пояснения можно найти на официальных веб-страницах.

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

В отсутствие таких инструментов, как Redmine, я обнаружил, что файлы Markdown полезны для этих целей. В целом для разработчиков эти файлы находятся в SCM и поставляются вместе с кодом.

LAIV
источник
1
Я согласен со всем, кроме доверия к W3Schools.com. Вы можете найти большую часть того, что есть на MDN, который имеет гораздо больше полномочий.
Alternatex
1
W3schools существует дольше, чем MDN. Я могу ошибаться, но я думаю, что в W3schools есть больше контента, учебных пособий и документации по веб-технологиям. Несмотря на свои проблемы, он продолжает оставаться одним из лучших справочников для начинающих, потому что его контент намного удобнее и интерактивнее. С другой стороны, у MDN есть отличное сообщество, поддерживающее его контент. Но с другой стороны, он никогда не может быть беспристрастным в своей документации, потому что у него есть браузер для защиты. В любом случае, я согласен с вами, сейчас у MDN, похоже, больше полномочий. если вы не возражаете, я добавлю ссылку на мой ответ.
Laiv
4

Ссылки на веб-сайты несколько проблематичны как документация, потому что Интернет не гарантирует, что контент, который вы видите за ними, будет таким же, что увидит будущий читатель документации. Если возможно, старайтесь ссылаться только на ресурсы, которые вряд ли изменятся.

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

Килиан Фот
источник
«Wayback Machine - Интернет-архив» (web.archive.org/) - хорошее место для проверки удаленного контента.
Кромстер