search

kbase / project_guides

This repo contains documents and guides that describe project principles, how-to docs, etc.
MIT License
7 stars 33 forks source link

Public Relations Approval Process Doc created #60

Closed meghandrake closed 8 years ago

meghandrake commented 8 years ago

With input from the Doc Team, I have created the Project Guide for the PR-Approval process.

aparkin commented 8 years ago

@meghandrake : This looks good. But:

1)Should we specify what is appropriate to submit through PR (Abstracts, posters, presentations, papers, ......)? 2) I am not entirely sure about: "If only one approval is received in 48 hours following submission to PR-approval, the single approval is fine and author can release their content. The author will reply to the approval email and to the PR-approval list, and indicate they are now releasing the content." I think it is probably ok if everyone on PR is aware of what might be red- flags,e tc. Not sure how to specify those effectively-- but authorship issues, specific functional claims that aren't entirely accurate, pre-publication release of data, etc. could all be things that raise flags. I'm probably worrying too much though.

nlharris commented 8 years ago

"1)Should we specify what is appropriate to submit through PR (Abstracts, posters, presentations, papers, ......)?" Um...that was stated in point #1:

  1. Team member drafts content for release (this includes posters, presentations, manuscripts, and anything that will be released publicly that is branded KBase). Does that need to be made clearer or more obvious?

"2) I am not entirely sure about: "If only one approval is received in 48 hours following submission to PR-approval, the single approval is fine and author can release their content." I understand why that makes you nervous. We wanted to put in something that (1) at least implicitly stated the turnaround time expect from the pr-approval committee (which hasn't always been prompt to respond), and (2) didn't leave the submitter in limbo if they didn't hear back from >1 pr-approval members. How about if we amend that statement to something like:

If only one approval is received in 48 hours following submission to PR-approval, and the content is not anything controversial or sensitive, the single approval is fine and author can release their content.

aparkin commented 8 years ago

@nomi Seems great.

nlharris commented 8 years ago

Ok. What is the best practice here? Should I start a new fork with an edit to the document, or wait for Meghan to make the suggested change, or what?

mlhenderson commented 8 years ago

Since Meghan submitted the PR, she should make the changes for her PR to be accepted. You (Nomi) could start a new PR with the updated text and reference Meghan's PR in a comment if you needed to move it along faster.

On Fri, Nov 13, 2015 at 10:57 AM, Nomi Harris notifications@github.com wrote:

Ok. What is the best practice here? Should I start a new fork with an edit to the document, or wait for Meghan to make the suggested change, or what?

— Reply to this email directly or view it on GitHub https://github.com/kbase/project_guides/pull/60#issuecomment-156523760.

meghandrake commented 8 years ago

Ok, i just updated the file!!

meghandrake commented 8 years ago

Ok I just updated the file further- thanks, Dan and Nomi.

nlharris commented 8 years ago

Is everyone satisfied with the content now? If so, can this PR be merged?

dangunter commented 8 years ago

I still don't understand the part about edits. For a publication, usually the text is being edited up to the day of submission. Edits after submission but before acceptance don't make a lot of sense, as reviewers may have more substantive comments. For a presentation, many of the slides may not exist until the plane flight over. Basically what I am thinking is that KBase PR should be approving rough drafts with an implicit agreement that people won't make serious changes without notifying the PR group.

On Tue, Nov 17, 2015 at 1:57 PM, Nomi Harris notifications@github.com wrote:

Is everyone satisfied with the content now? If so, can this PR be merged?

— Reply to this email directly or view it on GitHub https://github.com/kbase/project_guides/pull/60#issuecomment-157522063.

cshenry commented 8 years ago

So my recent book chapter is a good example of how this worked in practice. I submitted it in near final form to the PR team, and they edited it in detail. I integrated their edits along with some other final changes and submitted the paper. It worked well. Frankly, Nomi’s edits were amazing. We had eight people edit the paper before it went to Nomi, and she still found numerous errors and typos and confusing sentences where clarification was needed.

I think if the draft submitted for PR approval is a very rough draft, the author should state this and save the PR team the effort of a deep edit. But as long as the PR team is offering editing services, I urge folks on the project to avail themselves of the resource and run near final drafts by the team. It may be that this offer of editing won’t scale in the long run and this may need to be revised… but in the short run, it’s a way to increase the quality of our publications. I certainly valued the edits on my paper a great deal.

— Sent from Mailbox

On Wed, Nov 18, 2015 at 11:26 PM, Dan Gunter notifications@github.com wrote:

I still don't understand the part about edits. For a publication, usually the text is being edited up to the day of submission. Edits after submission but before acceptance don't make a lot of sense, as reviewers may have more substantive comments. For a presentation, many of the slides may not exist until the plane flight over. Basically what I am thinking is that KBase PR should be approving rough drafts with an implicit agreement that people won't make serious changes without notifying the PR group. On Tue, Nov 17, 2015 at 1:57 PM, Nomi Harris notifications@github.com wrote:

Is everyone satisfied with the content now? If so, can this PR be merged?

— Reply to this email directly or view it on GitHub https://github.com/kbase/project_guides/pull/60#issuecomment-157522063.

Reply to this email directly or view it on GitHub: https://github.com/kbase/project_guides/pull/60#issuecomment-157955003

dangunter commented 8 years ago

Sure, fine, but I just want to make sure that for lighter-weight more last-minute items there is a lighter-weight process that follows the spirit of the PR approval process without requiring unrealistic deadlines to be in place.

nlharris commented 8 years ago

When someone submits something for approval, I usually edit it and send it back within a few hours. That doesn't seem too unrealistic. I suggest planning ahead and not trying to write your abstracts in the last few hours before they're due. :-)

cshenry commented 8 years ago

Jeez Nomi… next you’ll be wanting pigs to fly. :)

— Sent from Mailbox

On Tue, Nov 24, 2015 at 3:23 PM, Nomi Harris notifications@github.com wrote:

When someone submits something for approval, I usually edit it and send it back within a few hours. That doesn't seem too unrealistic. I suggest planning ahead and not trying to write your abstracts in the last few hours before they're due. :-)

Reply to this email directly or view it on GitHub: https://github.com/kbase/project_guides/pull/60#issuecomment-159408772

meghandrake commented 8 years ago

Hi all, i just updated the file to be committed with changes enumerated by Nomi, but NOT the file title yet. I need to double check the best way to appropriately update the title. - Meghan

meghandrake commented 8 years ago

Ok i just updated the file name as discussed previously! - Meghan

meghandrake commented 8 years ago

I just updated the file further with a new file name and content regarding the External Communications Process.