Bao gồm một liên kết đến tài liệu liên quan trong thông báo lỗi?

Chúng tôi tạo ra một thư viện thương mại và các ví dụ mã đang được sử dụng bởi các nhà phát triển bên ngoài. Chúng tôi có tài liệu (đã đóng, có sẵn cho người dùng đã đăng ký) giải thích rộng rãi cách sử dụng thư viện.

Nhiều nhà phát triển là người dùng lần đầu, vì vậy rất nhiều lỗi thô sơ gặp phải.

Có phù hợp để bao gồm các liên kết đến tài liệu trong nhật ký lỗi không? Nhược điểm có thể là gì? Tôi có thể thấy trước một vài điều, nhưng dường như có thể vượt qua những điều sau đây

• URL tài liệu hết hạn
• Lỗi cụ thể của phiên bản không được phản ánh trong tài liệu mới nhất
• Một cái gì đó khác là sai, và chúng ta đang lãng phí thời gian của nhà phát triển bằng cách gửi anh ta đến một tài liệu không liên quan

Dưới đây là một ví dụ về những gì tôi muốn nói, đó có phải là một ý tưởng tốt để thêm văn bản in đậm?

[ERROR] Không thể thực hiện mục tiêu org.apache.maven.plugins: maven-archetype-plugin: 1.2.3: tạo (default-cli) trên dự án độc lập-pom: Archetype mong muốn không tồn tại (com.example.l Library. archetypes: library-archetype-blank: 1.2.3.0) -> Vui lòng xem http://example.com/docs/setting-up-an-archetype để biết thêm thông tin và có thể khắc phục sự cố

Theo các nguyên tắc thông báo lỗi này và kinh nghiệm của tôi, mọi người muốn tiết kiệm thời gian bằng cách không đọc tài liệu hoặc trợ giúp. Googling một lỗi cũng có thể vượt ra ngoài chúng, do đó, bao gồm một liên kết khi họ có lý do để nhấp vào nó.

Cuối cùng, có lẽ bạn đã biết Luật tài liệu máy tính đầu tiên của Nielsen: mọi người không đọc nó. Phát hiện này thậm chí còn mạnh hơn đối với các trang web, nơi người dùng thực sự né tránh bất kỳ việc đọc nào không cần thiết cho nhiệm vụ của họ. Bấm vào Trợ giúp? Không bao giờ.

Người dùng chỉ đọc tài liệu hệ thống khi họ gặp rắc rối (đó là Luật thứ hai). Họ đặc biệt chú ý khi họ muốn phục hồi từ một lỗi. Vì điều này, bạn có thể sử dụng các thông báo lỗi như một tài nguyên giáo dục để truyền đạt một lượng kiến ​​thức nhỏ cho người dùng. Tất nhiên, các thông báo lỗi phải ngắn gọn và chính xác, như tất cả nội dung Web. Tuy nhiên, thông báo lỗi vẫn có thể dạy cho người dùng một chút về cách hệ thống hoạt động và cung cấp cho họ thông tin họ cần để sử dụng nó tốt hơn. Để kết thúc, công nghệ cơ bản của Web tạo ra một hướng dẫn khác có thể:

Liên kết siêu văn bản có thể được sử dụng để kết nối một thông báo lỗi ngắn gọn với một trang với tài liệu nền bổ sung hoặc giải thích về vấn đề. (Đừng làm quá việc này, mặc dù.)

Vâng, chắc chắn nhất NHƯNG:

• Liên kết thối sẽ là một vấn đề, lý tưởng là tạo liên kết động từ một tài liệu đích đã biết nhưng lấy tiền tố từ một số dạng cấu hình. Nếu máy chủ thay đổi thì bạn có thể giữ mã cũ hơn bằng cách cập nhật thành phần cấu hình này. Bạn cũng có thể cung cấp tài liệu cục bộ chỉ bằng cách thay đổi cấu hình tiền tố này.
• Phiên bản : Theo cùng một tinh thần, nếu bạn có thể bao gồm phiên bản trong liên kết trong một số khả năng để liên kết luôn trỏ đến phiên bản chính xác của tài liệu.
• Làm cho tài liệu có thể chỉnh sửa Một cái gì đó giống như một trang web kiểu wiki cho tài liệu của bạn, nơi bạn có thể tự động sửa lỗi, lý tưởng cũng cho phép người dùng nhận xét trực tiếp trên trang. điều này sẽ giúp người dùng của bạn dễ dàng tham gia hơn và tìm thấy những gì họ cần và bạn sẽ nhận được thông tin vàng để giữ cho tài liệu của bạn luôn hoạt động tốt nhưng hãy đảm bảo bạn theo dõi nó thường xuyên và hầu hết đều tham gia tích cực.
• Các mẫu được tạo có hệ thống xây dựng của bạn tạo mẫu cơ bản cho tài liệu từ các chú thích trong mã trực tiếp. Mặc dù đơn giản, nhưng điều này sẽ đảm bảo rằng mọi liên kết luôn trỏ đến một tài liệu hợp lệ. Nếu bạn sử dụng wiki, hãy đảm bảo rằng bạn có thể đẩy các mẫu này một cách dễ dàng và đảm bảo rằng bạn có thể quảng bá trang web tài liệu giống như cách bạn làm cho mã của mình (có một trang dev khác với trang prod và mã quảng cáo cho prod sẽ thực hiện tự động chèn vào trang prod).

Nếu bạn phát triển bằng Java hoặc .NET, tài liệu có thể được bao gồm trong tệp jar hoặc tệp DLL và bằng cách thay đổi tiền tố, mã của bạn có thể tìm nạp cục bộ thay thế.

Nếu bạn chọn cách tiếp cận wiki, tôi nhiệt tình giới thiệu DokuWiki vì nó đơn giản và thực tế nó dựa trên các tệp văn bản phẳng sẽ rất thân thiện với tính năng tự động tiêm từ hệ thống xây dựng. Điều đó nói rằng, tôi không biết đủ về môi trường hoặc khách hàng của bạn để thực sự biết liệu đây có phải là một YMMV phù hợp hay không.

Một số công cụ thành công nhất mà tôi đã tạo có một cách tiếp cận tương tự trong đó thông báo lỗi được nhắm mục tiêu đến người dùng thực tế có khả năng thực hiện nhiệm vụ. Điều đó có nghĩa là tôi đã phải thực hiện RẤT NHIỀU việc bắt và gói ngoại lệ để đảm bảo lỗi ở mức độ trừu tượng thích hợp. Tôi cũng đảm bảo rằng mỗi thông báo lỗi sẽ bao gồm các nguồn lỗi và điểm có khả năng nhất đối với các giải pháp tiềm năng "Bạn có quên đặt giá trị cấu hình xxxx không?", "Đảm bảo xxx và yyy không xung đột bằng cách đặt cho chúng các tên khác nhau", v.v. Trong đó XXX và whatnot sẽ được tạo từ bối cảnh xảy ra lỗi.

Cách tiếp cận này có phần đơn giản hơn nhưng cũng hạn chế hơn. Tuy nhiên, mặt trái của nó là tài liệu sẽ luôn luôn có mặt khi cần thiết không thể thối liên kết.

Cách tiếp cận của bạn là sự phát triển tiếp theo. Phức tạp hơn nhiều nhưng cũng có lợi nhuận tiềm năng hơn nhiều. Nó sẽ tốn kém mặc dù nhưng nếu được thực hiện đúng sẽ dễ dàng trả hết cho chính nó.

Bạn nên ưu tiên chỉ vào tài liệu ngoại tuyến đi kèm với thư viện, thay vì trực tuyến.

(com.example.l Library.archetypes: library-archetype-blank: 1.2.3.0) -> Vui lòng xem /usr/share/myprog-3.8.1/docs/setting-up-an-archetype để biết thêm thông tin và có thể khắc phục sự cố

(rõ ràng nếu đó là một thư viện Windows, đường dẫn sẽ khác).

Những lợi ích ở đây là:

• Bằng cách này, tài liệu luôn đồng bộ với thư viện. Mọi người phát triển với và khắc phục sự cố các phiên bản thư viện cũ. Và công ty của bạn có thể thay đổi tên của nó, thay đổi tên của sản phẩm hoặc ai đó có thể thả bóng khi gia hạn example.com.

• Web thay đổi nhanh chóng. Liên kết bạn đưa ra là http, nhưng trong một vài năm, các trình duyệt chính của nó sẽ chỉ hỗ trợ https. Hoặc tất cả chúng ta có thể quay trở lại gophergiao thức.

• Xử lý sự cố ứng dụng không phải lúc nào cũng xảy ra trong một môi trường có truy cập internet (hoặc ít nhất là truy cập trực tiếp vào miền của bạn).

• Bạn đề cập đến tài liệu của bạn đằng sau một bức tường "xác thực". Phải tạo một tài khoản trên một trang web chỉ để hiểu một thông báo lỗi là không dễ chịu (đây là lý do tại sao SO không yêu cầu mọi người đăng nhập).

Có một cách thực sự thành công để tiếp cận vấn đề này. Đảm bảo ngoại lệ kết hợp với thông báo đủ độc đáo để dán chúng vào tìm kiếm trên web có thể dễ dàng tìm thấy tất cả các bài đăng có liên quan về chính xác vấn đề này.

Đây là lý do bí mật tôi ghét ngoại lệ con trỏ null rất nhiều. Chắc chắn tôi ghét rằng chúng tôi thậm chí phải kiểm tra null nhưng điều làm tôi bực mình nhất là, khi tôi gặp phải một, định danh duy nhất thực sự duy nhất tôi phải tìm kiếm là số dòng dễ bay hơi.

Vâng, tôi muốn có thể tìm kiếm những thứ này. Ồ chắc chắn, tôi biết nó đã xảy ra bởi vì một cái gì đó đã bị bỏ trống và sau đó được sử dụng. Điều không phải lúc nào cũng rõ ràng ngay lập tức là TẠI SAO một cái gì đó bị bỏ trống.

Vì vậy, chắc chắn, xem xét tất cả các giải pháp tài liệu khác. Nhưng điều lười biếng nhất bạn có thể làm sẽ giúp tôi điều tốt nhất chỉ là cho tôi thứ gì đó tôi có thể google.

Xin vui lòng?