È una cattiva pratica aggiungere collegamenti esterni nella documentazione?

Non penso che sia male, ma i link esterni hanno la cattiva abitudine di andare via durante il ciclo di vita di una soluzione. Quando lo fai, ti consiglio di inserire un riepilogo sufficiente per aiutare il lettore se il collegamento non è più funzionale.

Ecco perché le aziende dovrebbero avere il proprio repository di conoscenze. Ad esempio, la mia azienda ha un Redmine aziendale che viene utilizzato per la gestione del progetto, l'emissione di biglietti (monitoraggio di bug e attività) e lo strumento che utilizzo di più , una wiki . Tutte queste funzionalità per progetto: -)

Che cosa abbiamo nel wiki del progetto?

• Collegamenti alla documentazione: funzionale, tecnica, architettura, requisiti.
• Attori coinvolti: Project Manager, Devs, Key Account Manager del cliente, ...
• Descrizione per ambiente: macchine virtuali, O.S, server, configurazioni ...
• Varie: qualsiasi cosa importante / interessante (correlata al progetto) appresa durante la vita del progetto.
• Altre pagine.

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

• Overflow dello stack : voti positivi e ben argomentato
• Software Engineering Stackexchange : voti positivi e ben argomentato
• MKyong.com : Mi piace questa pagina. È davvero utile e le sue esercitazioni sono davvero facili da seguire
• MDN
• W3C.org
• W3Schools : la sua documentazione è interattiva (la maggior parte dei casi) e user-friendly.
• OWASP : per i problemi di referenziazione relativi a sicurezza e vulnerabilità
• Pagine web ufficiali: a volte i migliori tutorial o spiegazioni sono disponibili su pagine web ufficiali.

La mia bibliografia viene fornita con un riepilogo digitato da me, per assicurarmi 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 i file Markdown utili per questi scopi. Nel complesso per gli sviluppatori a causa di questi file sono in SCM e viene fornito con il codice.

I collegamenti al web sono in qualche modo problematici come documentazione perché Internet non garantisce che il contenuto che stai vedendo dietro di loro sarà lo stesso che un futuro lettore di documenti vedrà. Se possibile, cerca di collegare solo a risorse che è molto improbabile che cambino.

Ad esempio, quando si collega a Wikipedia, è necessario collegare esplicitamente alla versione di oggi anziché al nome dell'articolo generico. Per stackexchange.com, beh, al momento sembra improbabile che vada via, ma le domande vengono modificate o addirittura cancellate tutto il tempo, e tra cinque anni potrebbe essere arrivato un nuovo punto di incontro. Non rischierei di appendere la documentazione che porta un notevole valore commerciale in un sito così esterno alla tua organizzazione.