PEP 1: Replace/Update the "How to teach this" with "Documentation Updates"

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

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

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
50/100
Loại issue
Tài liệu
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
python
Lĩnh vực
documentation

Hướng nghiên cứu

Bắt đầu bằng cách xác định template hoặc hướng dẫn PEP định nghĩa phần “How to teach this”. Cập nhật phần đó để sử dụng “Documentation Updates” và đưa ra các prompt cụ thể để ghi lại tài liệu cho các tính năng hoặc thay đổi, sau đó kiểm tra việc sử dụng PEP hiện tại để đảm bảo tính nhất quán.

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

Mô tả

I would like to suggest an update to the "How to teach this" section in PEPs to "Documentation Updates".

As part of proposing new features or changes, it would be great if PEP authors also take into consideration of what docs need to be produced/updated.

For example, would the PEP require changes to the how-to doc? Will there be new tutorial section written? What other areas of Python docs need to be updated to accommodate this new change? Are there existing docs that will become outdated and need changing? I think all of these should be taken into consideration when proposing changes so that we can have up to date documentation alongside the changes.

I think the "How to teach this" section meant to address this, but in practise I find the use of this section has been inconsistent, so I recommend making the section be more explicit about documentation artifacts to accompany the feature/change.

I also find some of the "How to teach this" in current PEPs sometimes are sounding can sound hypothetical. I'm seeing phrases like "Teachers could say so and so to students".

Instead of imagining what teachers could say, I think it would be more helpful to come up with concrete plan of what documentation can be produced to assist users in learning and adopting the feature/change.

Ngôn ngữ chính
reStructuredText
Star
5k
Fork
1.8k
Merge trung bình
2 ngày 4 giờ
Pull request đã merge (30 ngày)
25

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

Mở hướng dẫn đóng góp

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 python/peps

Tất cả issue của python/peps

Issue tương tự

Thêm issue về Documentation

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.