Czy dodawanie linków zewnętrznych w dokumentacji jest złą praktyką?

9

Często rozwiązuję błędy, znajdując odpowiedź na temat Przepełnienia stosu. Czy złym zwyczajem jest dodawanie fragmentu, dlaczego zrobiłem to, co zrobiłem, a następnie dodawanie łącza do artykułu lub strony z Internetu?

documentation TruthOf42
źródło
Możliwy duplikat Czy mam dodać notatki MSDN lub linki przepełnienia stosu do kodu źródłowego?
komar
FWIW Robię to cały czas, a nawet zapytałem, jak to zrobić poprawnie na StackExchange . Nie to, że odpowiada na twoje pytanie, ale można tam znaleźć kilka argumentów za i przeciw.
4
Możliwy duplikat Czy w komentarzu programu można umieścić link do stron z pytaniami i odpowiedziami?
Doc Brown,
Czy pytanie dotyczy tylko linków (OK dla mnie), ponieważ wspominasz także o kopiowaniu części kodu / odpowiedzi. Zrobiłbym to tylko w celu wyjaśnienia złożonego algorytmu lub przetwarzania. Struktura kodu i nazewnictwo powinny być jasne niezależnie od tego, gdzie czytasz o rozwiązaniu.
Kwebble

Odpowiedzi:

14

Nie sądzę, że jest źle, ale linki zewnętrzne mają zły nawyk rezygnacji z cyklu życia rozwiązania. Robiąc to, zalecam umieszczenie wystarczającego podsumowania, które pomoże czytelnikowi, jeśli link przestanie działać.

Jim Rush
źródło
3
Dodanie podsumowania przydatnego z dwóch powodów: 1) Jak zauważył Jim, pomaga czytelnikowi zrozumieć, czy link jest nieaktualny, oraz 2) zmusza programistę do skopiowania kodu z linku, aby zrozumiał, co kopiują. Pomaga to upewnić się, że kod nie jest używany tylko dlatego, że „rozwiązuje problem”.
Mag Xy,
7

Dlatego firmy powinny mieć własne repozytorium wiedzy. Na przykład moja firma ma korporacyjną firmę Redmine, która służy do zarządzania projektem, sprzedaży biletów (śledzenia błędów i zadań) oraz narzędzia, z którego najczęściej korzystam - wiki . Wszystkie te funkcje dla jednego projektu :-)

Co mamy na wiki projektu?

  • Odnośniki do dokumentacji: funkcjonalne, techniczne, architektura, wymagania.
  • Zaangażowani aktorzy: kierownik projektu, deweloperzy, menedżerowie kluczowych klientów, ...
  • Opis według środowiska: maszyny wirtualne, system operacyjny, serwery, konfiguracje ...
  • Różne: Każda ważna / interesująca rzecz (związana z projektem), której nauczyłeś się w trakcie życia projektu.
  • Więcej stron.

Umieściłem bibliografię (linki) na Misc wiki. Ale tylko od tych, którym ufam:

  • Przepełnienie stosu : pozytywne głosy i dobrze uzasadnione
  • Inżynieria oprogramowania Stackexchange : Pozytywne głosy i dobrze argumentowane
  • MKyong.com : Podoba mi się ta strona. Jest to bardzo przydatne, a samouczki są bardzo łatwe do naśladowania
  • MDN
  • W3C.org
  • W3Schools : Jego dokumentacja jest interaktywna (większość przypadków) i przyjazna dla użytkownika.
  • OWASP : Do odwoływania się do problemów związanych z bezpieczeństwem i podatnościami
  • Oficjalne strony internetowe: Czasami najlepsze samouczki lub objaśnienia znajdują się na oficjalnych stronach internetowych.

Moja bibliografia zawiera spisane przeze mnie streszczenie, aby upewnić się, że rozumiem, do czego linkuję. Staram się zachować jasność Javadoc. Każdy link w kodzie odnosi się do wiki Redmine lub kodu problemu Redmine.

Wobec braku narzędzi takich jak Redmine, okazało się, że pliki Markdown są przydatne do tych celów. Ogólnie dla programistów ze względu na te pliki znajdują się w SCM i są dostarczane wraz z kodem.

Laiv
źródło
1
Zgadzam się ze wszystkim oprócz zaufania W3Schools.com. Możesz znaleźć większość tego, co jest w MDN, które ma znacznie większy autorytet.
Alternatex
1
W3schools istnieje już dłużej niż MDN. Mogę się mylić, ale myślę, że W3schools ma więcej treści, samouczków i dokumentacji technologii sieciowych. Pomimo problemów wciąż jest jednym z najlepszych referencji dla początkujących, ponieważ jego zawartość jest o wiele bardziej przyjazna dla użytkownika i interaktywna. Na plus MDN ma świetną społeczność wspierającą jego zawartość. Ale z drugiej strony, nigdy nie może być bezstronny w swojej dokumentacji, ponieważ ma przeglądarkę do obrony. Tak czy inaczej, zgadzam się z tobą, teraz dni MDN wydaje się mieć większy autorytet. jeśli nie masz nic przeciwko, dodam odniesienie do mojej odpowiedzi.
Laiv
4

Łącza do sieci są nieco problematyczne jako dokumentacja, ponieważ Internet nie gwarantuje, że zawartość, którą widzisz za nimi, będzie taka sama, jak zobaczysz przyszły czytnik dokumentów. Jeśli to możliwe, staraj się łączyć tylko z zasobami, których zmiana jest mało prawdopodobna.

Na przykład, kiedy łączysz się z Wikipedią, powinieneś wyraźnie połączyć się z dzisiejszą wersją zamiast ogólnej nazwy artykułu. W przypadku stackexchange.com w tej chwili wydaje się mało prawdopodobne, aby zniknęło, ale pytania są edytowane lub nawet usuwane przez cały czas, a za pięć lat może pojawić się nowy gorący punkt spotkań. Nie zaryzykowałbym powieszenia dokumentacji, która niesie ze sobą znaczną wartość biznesową na stronie tak zewnętrznej dla twojej organizacji.

Kilian Foth
źródło
„Wayback Machine - Internet Archive” (web.archive.org/) to dobre miejsce do sprawdzania usuniętych treści.
Kromster,