adding community documents support and first community document

[vsoch]

This pull request will add support for "Community Documents" - or living documents that the community is encouraged to collaborate on over time. As the first example, I'm including the "Why do we need a research software engineer role" document that a subset of folks have been working on.

The PR here includes the following:

• adding quick documentation in the README to describe community documentation
• the addition of a community document main page, and the first community document. Note that I've created a wider layout to be easier on the eyes for tables, reading, etc.
• a new collection for these docs, "docs"

Some comments:

• Does this belong here? Since this is a USRSE community resource, I think it belongs on the site (versus in another repository) so these important ideas are front and center.
• Why not a post?: Since these are living documents, they are timeless. If we encourage and expect changes over time, we cannot ascribe a publication date. It also wouldn't be good to have these conceptually different documents mixed up with posts, which are things that have a notable timestamp (event recaps, etc..)
• Organization: This could of easily gone under community, but since it's more of a resource (e.g., I would look to a community document to learn about something or use it for my own needs) I put it under resources (in the navigation and pages folder).

And here are some screen shots!

This is the community documents page, linked from the resources menu

This is the first community document - note the wider layout!

Signed-off-by: vsoch vsochat@stanford.edu

Description

Motivation and Context

Checklist:

• I have posted the link for the PR in the usrse slack (#website) to ask for reviewers
• I have previewed changes locally
• I have updated the CHANGELOG and (if necessary) the README.md

cc @usrse-maintainers

[vsoch]

• Link to community documents page
• First document

[cosden]

I don't have time right now to give this a proper review, but I strongly support the general idea of having a public facing collection of documents that could help support the community. Both the framework (a place on the website) and the content are things that I hope/had hoped would come out of the In-person community building workshop. So I'm very supportive of the idea.

I have only one concern, or maybe it's more of a "we need for a plan." As the organization grows, we need to ensure that anything posted on the website sends both a cohesive and positive message that aligns with our mission and code of conduct. How do we fairly (and without a major burden on anyone) review the content? I can barely keep up with PRs as it is now, adding (hopefully) multiple living documents could be challenging. Could we have a multi-person review on new documents, and then a designated document owner/reviewer? If it was a one time static-document it would require less review, but with this approach it could be more often. And how much should a reviewer be expected/allowed to edit or change a message. Is that the right way to do it?

[vsoch]

I have only one concern, or maybe it's more of a "we need for a plan." As the organization grows, we need to ensure that anything posted on the website sends both a cohesive and positive message that aligns with our mission and code of conduct. How do we fairly (and without a major burden on anyone) review the content? I can barely keep up with PRs as it is now, adding (hopefully) multiple living documents could be challenging. Could we have a multi-person review on new documents, and then a designated document owner/reviewer? If it was a one time static-document it would require less review, but with this approach it could be more often. And how much should a reviewer be expected/allowed to edit or change a message. Is that the right way to do it?

That's a good question! The quick answer is that we use GitHub PRs as we typically do as a method for review. We could extend this for community documents to require more reviews, or even require reviews from you guys in the executive committee / group. We could also require some number of GitHub reviews, and then to have the document approved by the committee at one of your meetings. Conceptually, this content isn't so different from the content we post on other parts of the site, anything that we post (blog posts, events, etc.) we would require to meet the Code of Conduct. It could definitely work to have the main submitter (myself in this case) take charge of being a leader for future document PRs changes. Another thing to note is that content probably won't get to being added until it's already gone through a lot of work in a Google Document (as this document did here) and I suspect we would catch CoC issues there long before getting here. In summary:

1. More community reviews plus the committee approval is required. The questions both should ask is if the document is of interest to the RSE community, and does it follow the Code of Conduct.
2. The owner of the document is responsible after it's added for leading PR reviewers, which again means bringing in some N number of reviewers, but probably not the executive committee as that's a lot of extra responsibility.
3. Documents should go through some extensive review before even coming here (e.g. if a community member shows up with something only they have worked on, it would be encouraged but suggested they try a Google Document first and get maybe 3-5 others working on it).

[vsoch]

And how much should a reviewer be expected/allowed to edit or change a message. Is that the right way to do it?

It's the same as open source, anyone can make a contribution or review and change, but it has to be reviewed by the owner (and then maybe a few others) and be approved before merge. If a contributor writes something that others don't agree with, then that's a good start for a discussion about the disagreement, which also can happen in the PR. It's a win win I think.

[vsoch]

@cosden I just updated the documentation in the README to include these procedural steps.

[vsoch]

The url error is for the umich career site, which appears to be giving a 403 error (weird). Since this needs more discussion, we don't need to triage this yet - I posted on slack to see if anyone knows about the site, and it also could just resolve itself. If it's still an issue when merge time comes I can remove that job posting.