Ist es eine schlechte Praxis, externe Links in die Dokumentation aufzunehmen?

9

Oft löse ich Fehler, indem ich die Antwort auf Stack Overflow finde. Ist es eine schlechte Praxis, einen Ausschnitt darüber hinzuzufügen, warum ich das getan habe, was ich getan habe, und dann einen Link zu einem Artikel oder einer Seite aus dem Web hinzuzufügen?

documentation TruthOf42
quelle
Mögliches Duplikat von Soll ich dem Quellcode MSDN-Notizen oder Stapelüberlauf-Links hinzufügen?
Mücke
FWIW Ich mache es die ganze Zeit und habe sogar gefragt, wie man das bei StackExchange richtig macht . Nicht, dass es Ihre Frage beantwortet, aber einige Argumente dafür und dagegen finden Sie dort.
4
Mögliches Duplikat von Ist es in Ordnung, in den Kommentaren eines Programms einen Link zu Q & A-Sites einzufügen?
Doc Brown
Ist die Frage nur über die Links (OK für mich), weil Sie auch das Kopieren von Teilen des Codes / der Antwort erwähnen. Dies würde ich nur tun, um einen komplexen Algorithmus oder eine komplexe Verarbeitung zu erklären. Codestruktur und Benennung sollten klar sein, unabhängig davon, wo Sie über eine Lösung lesen.
Kwebble

Antworten:

14

Ich denke nicht, dass es schlecht ist, aber externe Links haben die schlechte Angewohnheit, über den Lebenszyklus einer Lösung hinwegzugehen. Dabei empfehle ich, eine ausreichende Zusammenfassung zu erstellen, die dem Leser hilft, wenn der Link nicht mehr funktioniert.

Jim Rush
quelle
3
Hinzufügen einer Zusammenfassung, die aus zwei Gründen nützlich ist: 1) Wie Jim betonte, hilft dies dem Leser zu verstehen, ob der Link veraltet ist oder nicht, und 2) erzwingt, dass der Entwickler den Code aus dem Link kopiert, um zu verstehen, was er kopiert. Dies hilft sicherzustellen, dass Code nicht nur verwendet wird, weil "das Problem behoben wird".
Magier Xy
7

Aus diesem Grund sollten Unternehmen über ein eigenes Wissensrepository verfügen. Zum Beispiel hat mein Unternehmen eine korporative Redmine, die für das Projektmanagement, das Ticketing (Fehler- und Aufgabenverfolgung) und das von mir am häufigsten verwendete Tool, ein Wiki, verwendet wird . Alle diese Funktionen pro Projekt :-)

Was haben wir im Projekt-Wiki?

  • Links zur Dokumentation: Funktional, Technik, Architektur, Anforderungen.
  • Beteiligte Akteure: Projektmanager, Entwickler, Key Account Manager des Kunden, ...
  • Beschreibung pro Umgebung: Virtuelle Maschinen, Betriebssystem, Server, Konfigurationen ...
  • Sonstiges: Alle wichtigen / interessanten Dinge (im Zusammenhang mit dem Projekt), die während der Projektlaufzeit gelernt wurden.
  • Noch ein paar Seiten.

Ich habe Bibliographie (Links) in das Misc- Wiki gestellt. Aber nur von denen, denen ich vertraue:

  • Stapelüberlauf : Positive Stimmen und gut argumentiert
  • Software Engineering Stackexchange : Positive Stimmen und gut argumentiert
  • MKyong.com : Ich mag diese Seite. Es ist sehr nützlich und die Tutorials sind sehr einfach zu befolgen
  • MDN
  • W3C.org
  • W3Schools : Die Dokumentation ist interaktiv (in den meisten Fällen) und benutzerfreundlich.
  • OWASP : Zum Verweisen auf Sicherheits- und Sicherheitslückenprobleme
  • Offizielle Webseiten: Manchmal sind die besten Tutorials oder Erklärungen auf offiziellen Webseiten.

Meine Bibliographie enthält eine von mir eingegebene Zusammenfassung, um sicherzustellen, dass ich verstanden habe, worauf ich verlinke. Ich versuche Javadoc so klar wie möglich zu halten. Jeder Link im Code verweist auf das Wiki der Redmine oder den Problemcode der Redmine.

In Ermangelung von Tools wie Redmine habe ich festgestellt, dass Markdown- Dateien für diese Zwecke nützlich sind. Insgesamt sind Entwickler aufgrund dieser Dateien im SCM und kommen mit dem Code.

Laiv
quelle
1
Ich bin mit allem einverstanden, außer W3Schools.com zu vertrauen. Sie können das meiste auf MDN finden, was viel mehr Autorität hat.
Alternatex
1
W3schools gibt es schon länger als MDN. Ich kann mich irren, aber ich denke, W3schools hat mehr Inhalte, Tutorials und Dokumentation zu Webtechnologien. Trotz seiner Probleme ist es eine der besten Referenzen für Anfänger, da sein Inhalt viel benutzerfreundlicher und interaktiver ist. Auf der positiven Seite hat MDN eine großartige Community, die seinen Inhalt unterstützt. Auf der anderen Seite könnte es in seiner Dokumentation niemals unparteiisch sein, da es einen zu verteidigenden Browser hat. Wie auch immer, ich stimme Ihnen zu, jetzt scheint ein Tag MDN mehr Autorität zu haben. Wenn es Ihnen nichts ausmacht, werde ich den Verweis auf meine Antwort hinzufügen.
Laiv
4

Links zum Web sind als Dokumentation etwas problematisch, da das Internet nicht garantiert, dass der Inhalt, den Sie dahinter sehen, der gleiche ist, den ein zukünftiger Dokumentleser sehen wird. Versuchen Sie nach Möglichkeit, nur auf Ressourcen zu verlinken, deren Änderung sehr unwahrscheinlich ist.

Wenn Sie beispielsweise auf Wikipedia verlinken, sollten Sie explizit auf die heutige Version und nicht auf den allgemeinen Artikelnamen verweisen. Für stackexchange.com ist es im Moment unwahrscheinlich, dass es verschwindet, aber Fragen werden ständig bearbeitet oder sogar gelöscht, und in fünf Jahren könnte ein heißer neuer Sammelpunkt hinzugekommen sein. Ich würde nicht riskieren, Dokumentationen aufzuhängen, die einen erheblichen geschäftlichen Wert auf einer Site haben, die so außerhalb Ihres Unternehmens liegt.

Kilian Foth
quelle
"Wayback Machine - Internet Archive" (web.archive.org/) ist ein guter Ort, um nach gelöschten Inhalten zu suchen.
Kromster