Creates a contributing.md document

[jwdebelius]

Addresses issue #147. This is a first pass, roughly based on the sckit-bio contributing.md.

There are a few issues which need to be addressed here:

• Who is the target audience for IPython Notebooks?
• Format and documentation standards for IPython Notebooks
• Contribution of analyses outside the lab.
• Scope of sharing IPython notebooks.

[wasade]

credits and license section, and below, still don't render right. suggest checking out how github renders:

https://github.com/JWDebelius/American-Gut/blob/contributing/CONTRIBUTING.md

[jwdebelius]

@wasade @EmbrietteH: I think I have the formatting issues fixed.

[wasade]

Previously for references we just used hyperlinks... why the change?

[jwdebelius]

A more complete citation lets you know what you're looking at. Also, if you're linking out to a webpage that has since been take down, the description makes it easier to find that information

[wasade]

Right, but we've previously been linking to the Pubmed PMID which is presumably stable

On Thu, Oct 29, 2015 at 4:11 PM, J W Debelius notifications@github.com wrote:

A more complete citation lets you know what you're looking at. Also, if you're linking out to a webpage that has since been take down, the description makes it easier to find that information

— Reply to this email directly or view it on GitHub https://github.com/biocore/American-Gut/pull/148#issuecomment-152342723.

[jwdebelius]

For me, the first issue is the bigger one. I tend to get frustrated with the inline link-style citations following sentences, but typically read through numbered citations unless I want to follow up. Numbers also mean that I know you're referencing the same thing multiple times. But, ultimately, it's a stylistic question. I'm happy to support whichever in the group consensus, though.

[mortonjt]

One potential problem with Pubmed IDs is not all publications have Pubmed IDs. Not sure if this will be an issue here ...

Having complete citations seems appropriate - no strong preferences here.

What needs to be done to get this merged?

[jwdebelius]

The PMID thing isn't necessarily an issue, if we use citations.

At this point, there needs to be a concensus on the citation style. Perhaps, @EmbrietteH has a suggestion?

Alternatively, if @wasade agrees, we could use citations moving forward, and include a note that historic notebooks do not necessarily adhere to these standards?

[wasade]

My concern is that if the contributing requirements are too ridged, either people won't contribute or they'll disregard the requirements On Nov 16, 2015 11:29 AM, "J W Debelius" notifications@github.com wrote:

The PMID thing isn't necessarily an issue, if we use citations.

At this point, there needs to be a concensus on the citation style. Perhaps, @EmbrietteH https://github.com/EmbrietteH has a suggestion?

Alternatively, if @wasade https://github.com/wasade agrees, we could use citations moving forward, and include a note that historic notebooks do not necessarily adhere to these standards?

— Reply to this email directly or view it on GitHub https://github.com/biocore/American-Gut/pull/148#issuecomment-157109822.

[jwdebelius]

I'd rather have the standards, and not have people adhere to the letter than leave ambiguity. I don't expect people to adhere 100%, but I think setting the expectation of a narrative structure, logical flow, and adequate citations are critical.

[EmbrietteH]

What about doi? Even if there is no PMID, everything has a doi....

Sent from my HTC on T-Mobile 4G LTE

----- Reply message ----- From: "J W Debelius" notifications@github.com To: "biocore/American-Gut" American-Gut@noreply.github.com Cc: "Embriette Hyde" embriette.rose@gmail.com Subject: [American-Gut] Creates a contributing.md document (#148) Date: Mon, Nov 16, 2015 9:29 AM

The PMID thing isn't necessarily an issue, if we use citations.

At this point, there needs to be a concensus on the citation style. Perhaps, @EmbrietteH has a suggestion?

Alternatively, if @wasade agrees, we could use citations moving forward, and include a note that historic notebooks do not necessarily adhere to these standards?

---

Reply to this email directly or view it on GitHub: https://github.com/biocore/American-Gut/pull/148#issuecomment-157109822

[jwdebelius]

That was part of a discussion about link stability. I was advocating for a full citation, because then you can reference the same thing multiple times, have a title and author, etc. I find it more readable, and easier to track down what I need when a citation including authors, title, year and publication are provided. The model included a link to the actual document.

Daniel was arguing for links in the text, and that because most of what was being cited had a PMID, and therefore the links were stable.

I'm against DOI as a citation mechanism for what is primarily biological analysis.

On Mon, Nov 16, 2015 at 10:05 AM Embriette Hyde notifications@github.com wrote:

What about doi? Even if there is no PMID, everything has a doi....

Sent from my HTC on T-Mobile 4G LTE

----- Reply message ----- From: "J W Debelius" notifications@github.com To: "biocore/American-Gut" American-Gut@noreply.github.com Cc: "Embriette Hyde" embriette.rose@gmail.com Subject: [American-Gut] Creates a contributing.md document (#148) Date: Mon, Nov 16, 2015 9:29 AM

The PMID thing isn't necessarily an issue, if we use citations.

At this point, there needs to be a concensus on the citation style. Perhaps, @EmbrietteH has a suggestion?

Alternatively, if @wasade agrees, we could use citations moving forward, and include a note that historic notebooks do not necessarily adhere to these standards?

---

Reply to this email directly or view it on GitHub: https://github.com/biocore/American-Gut/pull/148#issuecomment-157109822

— Reply to this email directly or view it on GitHub https://github.com/biocore/American-Gut/pull/148#issuecomment-157121417.

[rob-knight]

PMID and DOI both provide stable links to the original article and will avoid endless additional threads about reference styles and compliance. Suggest using PMID if available, DOI if not (or maybe always DOI with PMID as available?)

On Nov 16, 2015, at 10:23 AM, J W Debelius notifications@github.com wrote:

That was part of a discussion about link stability. I was advocating for a full citation, because then you can reference the same thing multiple times, have a title and author, etc. I find it more readable, and easier to track down what I need when a citation including authors, title, year and publication are provided. The model included a link to the actual document.

Daniel was arguing for links in the text, and that because most of what was being cited had a PMID, and therefore the links were stable.

I'm against DOI as a citation mechanism for what is primarily biological analysis.

On Mon, Nov 16, 2015 at 10:05 AM Embriette Hyde notifications@github.com wrote:

What about doi? Even if there is no PMID, everything has a doi....

Sent from my HTC on T-Mobile 4G LTE

----- Reply message ----- From: "J W Debelius" notifications@github.com To: "biocore/American-Gut" American-Gut@noreply.github.com Cc: "Embriette Hyde" embriette.rose@gmail.com Subject: [American-Gut] Creates a contributing.md document (#148) Date: Mon, Nov 16, 2015 9:29 AM

The PMID thing isn't necessarily an issue, if we use citations.

At this point, there needs to be a concensus on the citation style. Perhaps, @EmbrietteH has a suggestion?

Alternatively, if @wasade agrees, we could use citations moving forward, and include a note that historic notebooks do not necessarily adhere to these standards?

---

Reply to this email directly or view it on GitHub: https://github.com/biocore/American-Gut/pull/148#issuecomment-157109822

— Reply to this email directly or view it on GitHub https://github.com/biocore/American-Gut/pull/148#issuecomment-157121417.

— Reply to this email directly or view it on GitHub https://github.com/biocore/American-Gut/pull/148#issuecomment-157126847.

[wasade]

Can this be merged?

[jwdebelius]

The document seems to be a moving target. It seems like based on the meeting on Tuesday, we were changing how we wanted to handle things like environments. So, this can be merged, it can be closed and updated with the current best practices...

[wasade]

is it accurate with respect to our own use of the repository though? i think this repo needs a lot of clean up and organization first.

[jwdebelius]

I don't think it's currently accurate. I don't know that it's every been accurate, especially given the primary processing set up.