È una cattiva pratica aggiungere collegamenti esterni nella documentazione?

9

Spesso mi trovo a risolvere i bug trovando la risposta su Stack Overflow. È una cattiva pratica aggiungere uno snippet del motivo per cui ho fatto quello che ho fatto e quindi aggiungere un collegamento a un articolo o una pagina dal web?

documentation

— TruthOf42
fonte

Possibile duplicato di Devo aggiungere note MSDN o collegamenti Stack Overflow al codice sorgente?

— moscerino

FWIW Lo faccio sempre e ho persino chiesto come farlo correttamente su StackExchange . Non che risponda alla tua domanda, ma alcuni argomenti a favore e contro possono essere trovati laggiù.

4

Possibile duplicato di È corretto inserire un collegamento ai siti di domande e risposte nei commenti di un programma?

— Doc Brown,

La domanda riguarda solo i collegamenti (OK per me), perché menzioni anche la copia di parti del codice / risposta. Questo è qualcosa che farei solo per spiegare un algoritmo o un'elaborazione complessi. La struttura e la denominazione del codice dovrebbero essere chiaramente indipendenti da dove leggi una soluzione.

— Kwebble

14

Non credo sia male, ma i collegamenti esterni hanno la cattiva abitudine di andare via nel ciclo di vita di una soluzione. Nel fare ciò, ti consiglio di mettere un riassunto sufficiente che aiuterà il lettore se il collegamento non funziona più.

— Jim Rush
fonte

3

L'aggiunta di un riepilogo utile per due motivi: 1) Come ha sottolineato Jim, aiuta il lettore a capire se il collegamento è obsoleto e 2) forza lo sviluppatore a copiare il codice dal collegamento per capire cosa stanno copiando. Questo aiuta ad assicurarsi che il codice non venga utilizzato solo perché "risolve il problema".

— Mago Xy,

7

Questo è il motivo per cui le aziende dovrebbero avere un proprio repository di conoscenze. Ad esempio, la mia azienda ha un Redmine corporativo che viene utilizzato per la gestione del progetto, ticketing (bug e tracciamento delle attività) e lo strumento che utilizzo di più, un wiki . Tutte queste caratteristiche per progetto :-)

Cosa abbiamo nel wiki del progetto?

Collegamenti alla documentazione: funzionale, tecnico, architettura, requisiti.
Attori coinvolti: Project Manager, Devs, Key Account manager del cliente, ...
Descrizione per ambiente: macchine virtuali, SO, server, configurazioni ...
Varie: qualsiasi cosa importante / interessante (relativa al progetto) appresa durante la vita del progetto.
Qualche altra pagina.

Ho messo la bibliografia (link) su Misc wiki. Ma solo da quelli di cui mi fido:

Stack Overflow : voti positivi e ben argomentato
Software Engineering Stackexchange : voti positivi e ben argomentati
MKyong.com : Mi piace questa pagina. È davvero utile e i suoi tutorial sono davvero facili da seguire
MDN
W3C.org
W3Schools : la sua documentazione è interattiva (la maggior parte dei casi) e intuitiva.
OWASP : per fare riferimento a problemi relativi alla sicurezza e alle vulnerabilità
Pagine Web ufficiali: a volte i migliori tutorial o spiegazioni si trovano nelle pagine Web ufficiali.

La mia bibliografia viene fornita con un riassunto scritto da me, al fine di garantire di aver capito a cosa sto collegando. Cerco di mantenere Javadoc il più chiaro possibile. Ogni collegamento nel codice fa riferimento al wiki di Redmine o al codice di emissione di Redmine.

In assenza di strumenti come Redmine, ho trovato utili file Markdown utili per questi scopi. Complessivamente per gli sviluppatori a causa di questi file sono in SCM e viene fornito con il codice.

— LAIV
fonte

1

Sono d'accordo con tutto tranne che fidarmi di W3Schools.com. Puoi trovare la maggior parte di ciò che c'è su MDN che ha molta più autorità.

— Alternatex,

1

W3schools è in circolazione da più tempo rispetto a MDN. Potrei sbagliarmi, ma penso che W3schools abbia più contenuti, tutorial e documentazione sulle tecnologie web. Nonostante i suoi problemi, è sempre stato uno dei migliori riferimenti per i principianti perché il suo contenuto è molto più intuitivo e interattivo. Tra i lati positivi, MDN ha una grande comunità che supporta il suo contenuto. Ma il lato negativo, non potrebbe mai essere imparziale nella sua documentazione perché ha un browser da difendere. Comunque, sono d'accordo con te, ora un giorno MDN sembra avere più autorità. se non ti dispiace, aggiungerò il riferimento alla mia risposta.

— Laiv

4

I collegamenti al Web sono in qualche modo problematici come documentazione perché Internet non garantisce che il contenuto che vedrai dietro di loro sarà lo stesso che vedrà un futuro lettore di documenti. Se possibile, cerca di collegarti solo a risorse che difficilmente cambieranno.

Ad esempio, quando ti colleghi a Wikipedia, dovresti collegarti esplicitamente alla versione odierna piuttosto che al nome generico dell'articolo. Per stackexchange.com, beh, al momento sembra improbabile che scompaia, ma le domande vengono modificate o addirittura cancellate continuamente, e tra cinque anni potrebbe essere arrivato un nuovo punto di raccolta. Non rischierei di appendere la documentazione che comporta un notevole valore commerciale in un sito così esterno alla tua organizzazione.

— Kilian Foth
fonte

"Wayback Machine - Internet Archive" (web.archive.org/) è un buon posto per controllare il contenuto cancellato.

— Kromster,