>
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