How to handle redundancy between params doc and tutorial doc

Đang mở
#20 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
20/100
Loại issue
Tài liệu
Độ rõ ràng
Cần làm rõ
Mức độ hoạt động
Đình trệ
Lĩnh vực
documentation

Hướng nghiên cứu

Bắt đầu bằng cách so sánh tài liệu về tham số với tài liệu hướng dẫn, tập trung vào phần văn bản giải thích, các ví dụ và liên kết của chúng. Công việc hoàn tất khi dự án có ranh giới được thống nhất giữa hai tài liệu và sự trùng lặp quá mức được giảm bớt mà không khiến người đọc tài liệu hướng dẫn phải phụ thuộc vào các liên kết thường xuyên.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

documentation

As I said in an earlier PR, my aim is for:

  • The parameters doc to be about what the parameters do.
  • The tutorial doc to be about what the user can do.

There will necessarily be considerable overlap, both the text and in the examples, but I'd like to avoid excessive redundancy.

I don't want the tutorial to "link out" very often. The tutorial reader is entitled to have the relevant material in-line, not linked to.

I'm thinking about having the parameters doc retain its explanatory text, but link to the specific tutorial section for examples. This would make the parameters doc much shorter -- a Good Thing in itself -- and also make the reader aware of the tutorial doc -- possibly another Good Thing.

I will value opinions.

Ngôn ngữ chính
Ruby
Star
71
Fork
27
Merge trung bình
3 giờ 3 phút
Pull request đã merge (30 ngày)
2

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của ruby/optparse

Tất cả issue của ruby/optparse

Issue tương tự

Thêm issue về Ruby

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.