Belgelere harici bağlantılar eklemek kötü bir uygulama mı?

Çoğunlukla Stack Overflow'daki cevabı bularak hataları çözerken kendimi bulurum. Neden yaptığımı yaptığım bir pasaj eklemek ve daha sonra web'den bir makaleye veya sayfaya bağlantı eklemek kötü bir uygulama mu?

Kötü olduğunu düşünmüyorum, ancak dış bağlantıların bir çözümün yaşam döngüsü boyunca gitme alışkanlığı kötü. Bunu yaparken, bağlantı artık işlevsel değilse okuyucuya yardımcı olacak yeterli bir özet koymanızı öneririm.

Bu nedenle şirketlerin kendi bilgi havuzlarına sahip olmaları gerekir. Örneğin, şirketimin proje yönetimi, biletleme (hatalar ve görev takibi) ve en çok kullandığım araç, wiki için kullanılan kurumsal bir Redmine var . Proje başına tüm bu özellikler :-)

Projenin wiki'sinde ne var?

• Belgelere bağlantılar: İşlevsel, Teknik, Mimari, gereksinimler.
• İlgili aktörler: Proje Yöneticisi, Devs, Müşterinin Kilit Hesap yöneticileri, ...
• Ortam başına açıklama: Sanal Makineler, İşletim Sistemi, sunucular, yapılandırmalar ...
• Misc: Projenin ömrü boyunca öğrenilen herhangi bir önemli / ilginç şey (proje ile ilgili).
• Biraz daha sayfa.

Misc wiki'ye bibliyografya (bağlantılar) koydum . Ama sadece güvendiğim kişilerden:

• Yığın Taşması : Olumlu oylar ve iyi tartışılmış
• Yazılım Mühendisliği Stackexchange : Olumlu oylar ve iyi tartışılmış
• MKyong.com : Bu sayfayı beğendim. Gerçekten kullanışlı ve eğitimlerini takip etmek gerçekten çok kolay
• MDN
• W3C.org
• W3Schools : Dokümantasyonu etkileşimli (çoğu durumda) ve kullanıcı dostudur.
• OWASP : Güvenlik ve güvenlik açıklarıyla ilgili başvuru sorunları için
• Resmi web sayfaları: Bazen en iyi öğreticiler veya açıklamalar resmi web sayfalarındadır.

Benim kaynakça ben bağlantı ettiğimi anlamış sağlamak amacıyla, tarafımdan aşağı yazdığınız bir özetle birlikte geliyor. Javadoc'u olabildiğince açık tutmaya çalışıyorum. Koddaki her bağlantı Redmine'ın wiki'sine veya Redmine'ın sorun koduna atıfta bulunuyor.

Redmine gibi araçların yokluğunda, bu amaçlar için yararlı Markdown dosyaları buldum . Genel olarak bu dosyalar nedeniyle geliştiriciler için SCM ve kod ile birlikte gelir.

Web bağlantıları biraz dokümantasyon gibi sorunludur, çünkü internet onların arkasında gördüğünüz içeriğin gelecekteki bir doktor okuyucusuyla aynı olacağını garanti etmez. Mümkünse, yalnızca değişmesi muhtemel olmayan kaynaklarla bağlantı oluşturmaya çalışın.

Örneğin, Wikipedia'ya bağlandığınızda, genel makale adı yerine bugünün sürümüne açıkça bağlanmanız gerekir. Stackexchange.com için, şu anda gitme olasılığı düşük görünüyor, ancak sorular her zaman düzenleniyor veya hatta siliniyor ve beş yıl içinde yeni bir toplanma noktası ortaya çıkmış olabilir. Kuruluşunuz için bu kadar harici bir sitede önemli işletme değeri taşıyan belgeleri asmayı riske atmam.