DOC: Add a more welcoming tone for new contributors
State: closed

- [x] closes #17579 
- [x] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] whatsnew entry


Labels:
name: Docs

Comments:
@willingc : Thanks for the PR!  Reading this, I'm a little confused by which section of the docs is scaring away new contributors.  In fact, if anything, it's scaring away current contributors from writing new docs because it might come across as too technical and less understandable for the general user.

Could you clarify what you found "less friendly" about the existing documentation?
> Could you clarify what you found "less friendly" about the existing documentation?

The existing wording reinforces the myth that documentation is not as valuable as code. (i.e. `If you're not the developer type, contributing to the documentation is still of huge value.`) I doubt that the author's intent was to split folks into "developer"/"not developer". It sends the message "even if you can't write code... the docs are *still* valuable".

Just to clarify my thoughts...I think the pandas contributors and documentation are wonderful. Please consider my comments/suggestions as something that I have found in other projects to improve open source documentation and strengthen the contributor community.
> The existing wording reinforces the myth that documentation is not as valuable as code

Ah, I see.  So we're definitely trying to not scare away non-devs.  We explicitly refer non-developers because we've had several people file issues who then back away from contributing because they don't believe they're "dev-like" and therefore can't contribute.

That being said, I see no reason with modifying that one sentence (if that's your issue) instead of modifying the entire two paragraphs.  How about this:

"If you're not the developer type, contributing to the documentation is *equally as valuable* to us."
> That being said, I see no reason with modifying that one sentence (if that's your issue) instead of modifying the entire two paragraphs. 

I modified both paragraphs to create an [affirmative tone](https://docs.python.org/devguide/documenting.html#affirmative-tone) and [economy of expression](https://docs.python.org/devguide/documenting.html#economy-of-expression).

I'm happy to just modify the one sentence if that is what you prefer. Just let me know.
Compared to the original, the modifications dampen the enthusiasm that the author originally intended with these paragraphs.  Therefore, I would prefer to modify that one sentence, and this PR will be on its way.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=h1) Report
> Merging [#17580](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/37e23d03e1ba2298d9df05ded69028dfac0e823e?src=pr&el=desc) will **decrease** coverage by `0.01%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/17580/graphs/tree.svg?token=eZ4WkYLtcO&src=pr&height=150&width=650)](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #17580      +/-   ##
==========================================
- Coverage   91.22%    91.2%   -0.02%     
==========================================
  Files         163      163              
  Lines       49625    49625              
==========================================
- Hits        45270    45261       -9     
- Misses       4355     4364       +9
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.99% <ø> (ø)` | :arrow_up: |
| #single | `40.2% <ø> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.77% <0%> (-0.1%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=footer). Last update [37e23d0...029f25d](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=h1) Report
> Merging [#17580](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/37e23d03e1ba2298d9df05ded69028dfac0e823e?src=pr&el=desc) will **decrease** coverage by `0.04%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/17580/graphs/tree.svg?width=650&height=150&src=pr&token=eZ4WkYLtcO)](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #17580      +/-   ##
==========================================
- Coverage   91.22%   91.18%   -0.05%     
==========================================
  Files         163      163              
  Lines       49625    49626       +1     
==========================================
- Hits        45270    45249      -21     
- Misses       4355     4377      +22
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.96% <ø> (-0.03%)` | :arrow_down: |
| #single | `40.19% <ø> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/plotting/\_tools.py](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL190b29scy5weQ==) | `72.92% <0%> (-6.08%)` | :arrow_down: |
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.52% <0%> (-0.21%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.77% <0%> (-0.1%)` | :arrow_down: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `96.9% <0%> (ø)` | :arrow_up: |
| [pandas/plotting/\_converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb252ZXJ0ZXIucHk=) | `63.38% <0%> (+0.15%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=footer). Last update [37e23d0...8daa606](https://codecov.io/gh/pandas-dev/pandas/pull/17580?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

> In the past that’s what we’ve done, but I’m open to logging doc changes here.

Sure, we can certainly discuss that, but perhaps better if we table for a broader discussion, when the original focus was just to improve the contributing docs.
> Sure, we can certainly discuss that, but perhaps better if we table for a broader discussion

This seems like an opportune place to discuss it. @jorisvandenbossche Thoughts?

My thoughts are

Pros:

1. pixels are cheap. Having more items in the whatsnew isn't a bad thing
2. Contributors get to see their work reflected in the release notes
3. Emphasizes that we value doc contributions, they don't have special rules

Cons:

1. The whatsnew is a common source of merge conflicts, which can be tough for new contributors (but we maintainers can handle them in the web UI with little difficulty, so not a big problem)

Overall a 👍  from me

---

@willingc We're aware of the Travis failure (new release of Pyarrow broke a test), so no need to worry about that.
this PR is fine. As far as what'snew for documentation, we generally don't do this unless its a newish section, e.g. something we would want to point users to.
 +1 from me as well. @TomAugspurger gave a good summary.

BTW, about the actual PR. @willingc I find your original rewrite of the first sentence better (which left out the "If you're not the developer type"). 
@jorisvandenbossche : I actually liked that part because it directly addresses those who actually don't believe that they are (people say that explicitly as reasons for being wary of contributing).
> As far as what'snew for documentation, we generally don't do this unless its a newish section, e.g. something we would want to point users to.

@jorisvandenbossche @TomAugspurger : I actually wasn't aware of this, but in light of this comment, is this change really a newish section?
> > As far as what'snew for documentation, we generally don't do this unless its a newish section, e.g. something we would want to point users to.

> @jorisvandenbossche @TomAugspurger : I actually wasn't aware of this, but in light of this comment, is this change really a newish section?

I think we're discussing the merits of changing the informal policy of not having whatsnew notes. Let's not be constrained by past habits :)
> I think we're discussing the merits of changing the informal policy of not having whatsnew notes.

Right, but I'll bring up my question again: why in this PR?  Something like this is better suited for an issue that the original changes are getting lost in a larger discussion.

> Let's not be constrained by past habits :)

I might add that a decision like this, while not necessarily as heavy as say an API change does have a noticeable impact on what we share in the `whatsnew` documentation.  I'm not getting stuck in old habits, but I am hesitant to alter how we document changes so late in the release cycle (IINM, the end of the month is our goal).
Ok. I've made one last pass at this PR. I've removed the whatsnew change, but I hope you will reconsider your policy in a future PR. I've put my original first sentence back and made the "you don't need to be a developer" the second sentence. Feel free to make any additional changes by editing the PR directly. Thanks.
> Ok. I've made one last pass at this PR. I've remove the whatsnew change, but I hope you will reconsider your policy in a future PR.

Absolutely.  I think it's safe to say that you don't really need to hope, as we're reconsidering it right now in your PR, for better or worse. 😄 
@willingc : Actually, why don't you open an issue for this (I'm on my phone, so hard to do).  Then we can transfer the conversation there and merge this in.
No problem @gfyoung. I'll open the issue. Thanks!
Thanks @willingc!