Populating the Contributor's Guide

[brian-rose]

What do want to the Contributor's Guide to look like?

We got a first draft of the Contributor's Guide done following discussion in #4, and #15 extends this to include instructions on building the html on a local machine. That's already out of date because #17 adds auto-building of PRs on readthedocs, which is awfully convenient for developing and testing new content.

In light of our discussions around entraining the community into Project Pythia, my view is that the scope of the Contributor's Guide should be broad. It should be a gateway for people to get involved, and must be accessible to all skill levels.

I think it would be terrific to cross-link our Contributor's Guide with some of the training material that will populate the portal, so that we have well-maintained tutorials and instructions that allow someone to go from total beginner to submitting PRs with new portal content.

What do people think? And are there any good examples of Guides from other community projects that can serve as models?

[clyne]

I strongly concur with making the contributors guide broad and accessible to all levels. Teaching folks how to set up their environment correctly with conda, and navigate the use of GitHub will benefit not only our project by facilitating contributions, but I believe are becoming essential skills for our scientists. Unfortunately, these technologies still present barriers for many IMHO. The NCAR GeoCAT team recently completed a contributor's guide that I will in the most positive light refer to as a "contributors guide for dummies". Though there is a long preamble specific to the GeoCAT organization, I would offer it up as a guide we should look at for Pythia: https://geocat.ucar.edu/pages/contributing.html

[jukent]

Either the auto-building from #17 is not working or is non-obvious. I would like to help add this content but I'm not sure how to use the auto-build method of building the site. E: I think it is working now. Both #24 and #25 needed an update from main to do the Read the Docs build.

[jukent]

Are there any other aspects we can identify as missing from the contributors guide?

[clyne]

Are there any other aspects we can identify as missing from the contributors guide?

I think we're good now. We'll have to revisit once we start hosting our own content (e.g. jupyter notebooks). We can either close this issue and open a new one for the next generation contributor guide, or just leave this one open. Doesn't matter to me, but if the former I think we should capture Brian's initial comments.

[brian-rose]

Agreed that this will need revisiting once we start hosting content. I suggest leaving this issue open for now, as a signal that the current guide is temporary.

[clyne]

@brian-rose should we close this? There is a separate issue, #104 that I think addresses that gaps that weren't completed in PR #97

[brian-rose]

@brian-rose should we close this? There is a separate issue, #104 that I think addresses that gaps that weren't completed in PR #97

Yes, this issue has run its course! I will close now.