a) this seems to be "well-defined", and imho, suitable as "easy", etc..
Part of this could potentially be suitable as an "easy" issue, but I'm not certain that it would make for a good first PR, since it is involving a fairly important and widely used section of the devguide. Many newcomers may not be familiar with what would be considered "appropriate usage" of the Sphinx roles in news entries. When I think of issues that would be good first PRs involving documentation, I generally think of grammar/spelling improvements or perhaps more objective fixes. This section might be a little bit too subjective though.
b) isn't this something we want new people to be more aware of (as you said, you have been working with this for a year)
I think you might be confusing me with someone else, as I've only been contributing to Python since June of this year. I've built up some amount of experience from PRs I've submitted as well as PR reviews, but I would still consider myself to be a more recent contributor. If I come across as having more experience though, that's certainly a good thing. (:
c) it is an area (Documentation) I have clearly 'missed' as I focused on 'other things', and, with myself and many projects I have worked on over the years - Documentation seems to come in last. Getting new (and newish, as myself) working here only makes us better suited for review in the future.
I definitely agree that we should try to come up with ways to improve the
interaction with the documentation (particularly with the devguide). A
great way to do that can be cleaning up existing sections, but for reasons
previously stated, I'm not certain that this issue is particularly well
suited for that. It's "well-defined" from feedback in the mailing list
discussion, but I think it would benefit from being written by someone with
some experience in news entries, reST and Sphinx markup, and documentation
in general.
However, a great way that anyone could help out would be through providing
feedback on the PR once it's open. Providing feedback on PRs is great way
to improve experience in an area, and also helps to deal with a major
bottleneck for Python development in general. We have far more people
submitting PRs than reviewers.
Once I open the PR for it in the devguide, I'll be sure to send a message
in this topic which includes a link to it. It would greatly benefit from
review from those who are less familiar with documentation. That will help
to ensure the section is easy to understand for the intended target
audience. Of course, it would also benefit from those are are experienced
as well, to ensure it is as accurate as possible.
Thanks,
Kyle Stanley
On Fri, Aug 16, 2019 at 4:48 AM Michael
On 16/08/2019 05:31, Kyle Stanley wrote:
Yeah definitely, it was my intention to mention this in the devguide, particularly with adding an example of the Sphinx roles being used and explaining appropriate usage. I hadn't thought of linking to the list of roles (https://devguide.python.org/documenting/#id4), but that's definitely a good idea to include. I was just waiting for everyone to get a chance to provide feedback on the topic before expanding the devguide.
After the devguide is updated, I was also planning on adding the markup to 3.8's Misc/NEWS entries (in the appropriate branch, as Ned recommended), and then work on the 3.9. I'll probably split it into several smaller PRs so it's easier to review.
There has been "a lot" of discussion re: things for new contributors to do and learn.
a) this seems to be "well-defined", and imho, suitable as "easy", etc.. b) isn't this something we want new people to be more aware of (as you said, you have been working with this for a year) c) it is an area (Documentation) I have clearly 'missed' as I focused on 'other things', and, with myself and many projects I have worked on over the years - Documentation seems to come in last. Getting new (and newish, as myself) working here only makes us better suited for review in the future.
So, I guess this is an area where you could "mentor", perhaps create "issues" that specify the "paragraphs", or whatever you think are appropriate 'chunks' to make review sensible (if not also easier).
Michael