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

Reply via email to