Có phải là thực tế xấu để thêm các liên kết bên ngoài trong tài liệu?

Thường thì tôi thấy mình giải quyết các lỗi bằng cách tìm câu trả lời trên Stack Overflow. Có phải là một thực tế xấu khi thêm một đoạn lý do tại sao tôi đã làm những gì tôi đã làm và sau đó thêm một liên kết đến một bài viết hoặc trang từ web?

Tôi không nghĩ nó xấu, nhưng các liên kết bên ngoài có thói quen xấu là đi theo vòng đời của một giải pháp. Khi làm như vậy, tôi khuyên bạn nên đặt một bản tóm tắt đầy đủ sẽ giúp người đọc nếu liên kết không còn hoạt động.

Đây là lý do tại sao các công ty nên có kho lưu trữ kiến ​​thức của riêng mình. Ví dụ, công ty của tôi có Redmine tập thể được sử dụng để quản lý dự án, bán vé (theo dõi lỗi và nhiệm vụ) và công cụ tôi sử dụng nhiều nhất, wiki . Tất cả các tính năng này cho mỗi dự án :-)

Chúng ta có gì tại wiki của dự án?

• Liên kết đến tài liệu: Chức năng, Kỹ thuật, Kiến trúc, yêu cầu.
• Các diễn viên tham gia: Quản lý dự án, Devs, Quản lý tài khoản chính của khách hàng, ...
• Mô tả cho mỗi môi trường: Máy ảo, HĐH, máy chủ, cấu hình ...
• Misc: Bất kỳ điều quan trọng / thú vị nào (liên quan đến dự án) đã học được trong suốt cuộc đời của dự án.
• Một số trang nữa.

Tôi đặt thư mục (liên kết) tại Misc wiki. Nhưng chỉ từ những người tôi tin tưởng:

• Stack Overflow : Phiếu bầu tích cực và được tranh luận tốt
• Kỹ thuật phần mềm Stackexchange : phiếu bầu tích cực và được tranh luận tốt
• MKyong.com : Tôi thích trang này. Nó thực sự hữu ích và hướng dẫn của nó rất dễ thực hiện
• MDN
• W3C.org
• W3Schools : Tài liệu của nó có tính tương tác (hầu hết các trường hợp) và thân thiện với người dùng.
• OWASP : Để tham khảo các vấn đề liên quan đến bảo mật và lỗ hổng
• Các trang web chính thức: Đôi khi các hướng dẫn hoặc giải thích tốt nhất là tại các trang web chính thức.

Thư mục của tôi đi kèm với một bản tóm tắt được tôi gõ xuống, để đảm bảo rằng tôi đã hiểu những gì tôi đang liên kết đến. Tôi cố gắng giữ Javadoc rõ ràng nhất có thể. Mọi liên kết trong mã đều tham chiếu wiki của Redmine hoặc mã vấn đề của Redmine.

Khi không có các công cụ như Redmine, tôi thấy các tệp Markdown hữu ích sẽ hữu ích cho các mục đích này. Nhìn chung cho các nhà phát triển do các tệp này nằm trong SCM và đi kèm với mã.

Các liên kết đến web có chút vấn đề như tài liệu vì internet không đảm bảo rằng nội dung bạn nhìn thấy đằng sau chúng sẽ giống với nội dung mà người đọc tài liệu trong tương lai sẽ thấy. Nếu có thể, hãy cố gắng chỉ liên kết với các tài nguyên rất khó thay đổi.

Chẳng hạn, khi bạn liên kết với Wikipedia, bạn nên liên kết rõ ràng với phiên bản hôm nay thay vì tên bài viết chung chung. Đối với stackexchange.com, tại thời điểm này dường như không thể biến mất, nhưng các câu hỏi được chỉnh sửa hoặc thậm chí xóa mọi lúc, và trong năm năm nữa, một điểm tập hợp mới nóng hổi có thể xuất hiện. Tôi sẽ không mạo hiểm treo tài liệu mang giá trị kinh doanh đáng kể trên một trang web rất bên ngoài tổ chức của bạn.