Update home page governance links#71
Conversation
…readme adds links in Project and community section of the docs homepage to the new org contributing guide and readme, and tweaks some wording with the other links
NucciTheBoss
left a comment
There was a problem hiding this comment.
Like the additional resources for finding our project on GitHub. Some suggestions around the resources we're linking to. The tl;dr is that I don't think we should directly link to an individual file on GitHub from our RTD site. I'd worry that non-hackers and developers would find it unprofessional.
index.md
Outdated
| * [Get the latest news on Discourse](https://discourse.ubuntu.com/c/hpc/151) | ||
| * [Ask and answer questions on GitHub](https://github.com/orgs/charmed-hpc/discussions/categories/q-a) | ||
| * [See our Contributing guide](https://github.com/charmed-hpc/.github/blob/main/CONTRIBUTING.md) | ||
| * [Visit the Charmed HPC GitHub Organization for more information or to ask for support](https://github.com/charmed-hpc) |
There was a problem hiding this comment.
I wouldn't say "ask for support" here. We don't want folks blowing up our issue trackers with personal enhancement requests or edge-case scenarios. If folks are looking for support, I'd want to direct them straight to the Q&A section on GitHub Discussions, or to our Matrix channel. I'd think it be better to say "Contribute to Charmed HPC":
| * [Visit the Charmed HPC GitHub Organization for more information or to ask for support](https://github.com/charmed-hpc) | |
| * [Contribute to Charmed HPC on GitHub](https://github.com/charmed-hpc) |
My reasoning is that if folks are visiting the project on GitHub, this likely means they're interested in contributing in the form of bug reports, pull requests, or documentation fixes/additions.
There was a problem hiding this comment.
I wanted to explicitly state the 'ask for support' aspect, but I agree that may be too open ended for that specific link. Should the Discourse link instead mention support? Or maybe Matrix's?
index.md
Outdated
| * [Join the Ubuntu HPC community on Matrix](https://matrix.to/#/#hpc:ubuntu.com) | ||
| * [Get the latest news on Discourse](https://discourse.ubuntu.com/c/hpc/151) | ||
| * [Ask and answer questions on GitHub](https://github.com/orgs/charmed-hpc/discussions/categories/q-a) | ||
| * [See our Contributing guide](https://github.com/charmed-hpc/.github/blob/main/CONTRIBUTING.md) |
There was a problem hiding this comment.
I'd rather not link directly to a "bespoke" file on GitHub. It feels unprofessional especially if you're not someone who's immersed in hacker culture. I'd be concerned that someone who's evaluating Charmed HPC from a purchasing standpoint might see this as a quick hack.
I think this URL is captured by my suggestion below. If someone's interested in contributing directly to Charmed HPC, they'll go to the GitHub organization, see the excellent profile README, and get the link to the global CONTRIBUTING.md document from there. I'd only include a direct link to a contributing guide here if it was hosted directly on our RTD site as a nicely rendered page rather than a single file on GitHub.
There was a problem hiding this comment.
I totally agree on not linking to the file that way!.. I felt odd adding it but wasn't sure what the ideal work-around would be. I do intend to replace that link with the RTD Contributing page once it's live, so maybe this line should just not exist until it can have the correct link.
Agreed on pointing to the org README capturing some of that, but I'll want to make sure that if the line says it's specifically for contributing then the link goes directly to contributing docs. Not that it's hard to find in the README, but we should be as consistent as possible with where we link vs what we say is being linked.
Co-authored-by: Jason Nucciarone <40342202+NucciTheBoss@users.noreply.github.com>
NucciTheBoss
left a comment
There was a problem hiding this comment.
Just one small nit and then I'm good to merge this PR 🤩
Co-authored-by: Jason Nucciarone <40342202+NucciTheBoss@users.noreply.github.com>
Pre-submission checklist
Summary of Changes
Updates the home page Project and community section to include links for the newly created org-level CONTRIBUTING.md guide and README.md. Also tweaks some wording in the other links to make the flow more consistent.
Related Issues, PRs, and Discussions
Pull Request to add org-level README - merged
Pull Request to add org-level CONTRIBUTING.md guide - merged