Skip to content

Improve contributing documentation clarity#2568

Open
Karanrajpurohit855 wants to merge 2 commits intoarviz-devs:mainfrom
Karanrajpurohit855:improve-contributing-docs
Open

Improve contributing documentation clarity#2568
Karanrajpurohit855 wants to merge 2 commits intoarviz-devs:mainfrom
Karanrajpurohit855:improve-contributing-docs

Conversation

@Karanrajpurohit855
Copy link
Copy Markdown

Fixes #1754

Improved contributing documentation by adding clearer steps and beginner-friendly instructions.

Copy link
Copy Markdown
Contributor

@aloctavodia aloctavodia left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for your contribution. This may be potentially useful, but it needs much more work.

Comment thread CONTRIBUTING.md

If you are new to open source:
- Start with small documentation improvements
- Look for issues labeled "User Documentation"
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't have this label. I think the label is "documentation", please double-check. Also, "good first issue" could be useful (also double check the name).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see that we have that label, my bad!

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moreover, I strongly disagree with this statement. Things labeled "User Documentation" are not necessarily easier than the rest. If a tag is mentioned it should be the "Beginner" one but we don't have much capacity to dedicate to issue triaging, so I would instead focus on advise that is not label dependent. It is key to understand what the issue is talking about, if it is still relevant, if it can be reproduced... Even for issues labelled "Beginner" when we have them they might be for someone who is a beginner on open source but already an intermediate ArviZ user, or for someone who is new to ArviZ but somewhat familiar with open source.

Comment thread CONTRIBUTING.md
We welcome a wide range of contributions, not only code!
Even improving documentation or fixing typos is a valuable contribution to ArviZ.

## How to contribute
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is only for people that wants to contribute code. You don't need to do this to report issues. So it should be in a different place, maybe a subsection of "contributing code". Additionally, if someone is a beginner, does this list help or do we need something more explicit? And if not a beginner, not very useful, which makes the "For Beginners" heading weird.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this whole "how to contribute" section should be removed. This is only a bullet point version of the content already present in the first link within the "Contributing code" section of this same page.

Copy link
Copy Markdown
Member

@OriolAbril OriolAbril left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR description says this is supposed to close #1754 but at least for now this is very clearly not the case. The issue is very clear that the updates should be done to the contributing guide on the website, not to this CONTRIBUTING.md and has a much larger scope

Comment thread CONTRIBUTING.md
5. Commit and push
6. Open a Pull Request

## For Beginners
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be useful to add some content specific to how beginners can find things to work on within the contributing guide. That being said, I am strongly against adding this directly to this markdown file. We already have a much more extensive contributing guide on the website so I think we should keep this page extremely short and with links to that page. A potential location for this kind of content could be https://python.arviz.org/en/stable/contributing/contributing_prs.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Extend contributing docs

3 participants