> 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 <aixto...@felt.demon.nl> wrote: > 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 > > >
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-le...@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/ROXFQX7ZDXFH5YRNGYZU3KCF7GR5QQLL/
