10/22 commits:

• applied minor review
• line break for each sentence
• fix leadership structure figure rendering

pinging @sappelhoff @effigies for review

It's not obvious to me why this should move from Google Docs into Markdown... Was this a decision by the steering committee? This isn't really part of the spec, and once here, every minor change becomes a PR.

This is what was originally planned in regards to the Governance document. The Steering Group has not ruled on the location they think the Governance document should live

I initially approved this PR, because the document seemed to fit with these documents that we already host in our specification repo:

• DECISION-MAKING
• CONTRIBUTING
• etc.

but @effigies comment makes sense, so I'll dismiss my approving review until we've heard some more arguments or a decision by the steering group.

I kinda like having the governance doc in the github repository.....but I also like the idea of having the steering group comment on that point. @franklin-feingold - can you add it to the agenda for the next meeting?

I like having the governance doc published in a place where it can be found by all current and future stakeholders (i.e. somewhere online where it gets crawled/indexed by Google/Bing/DuckDuckGo/etc) and maintained in a transparent way (i.e. on github). However, it is conceptually not as tightly linked to the "bids-specification" repository as the DECISION-MAKING and CONTRIBUTING documents are. The governance doc could e.g. also be in the bids-website repo and on the main website

Why not just maintain it in Google Docs, and then embed the content into GitHub pages where it's needed? I +1 that after moving collaborative content to GitHub, it introduces a barrier to contribution to those that aren't comfortable with version control, it removes the nice ability to have chains of comments and discussion, and for multiple people to (more easily) work on the same draft.

One of the reason for moving the detailed discussion on the specification and the BEPs away from google docs towards github (as discussed in detail on the mailing list) was that google docs are not indexed in search engines and hence cannot be found if you don't know the direct link, that resolved discussions/comments cannot be read on google docs (i.e. the comments disappear), that it is not clear who commented/changed what after merging changes, and that version information gets lost once the document is closed. E.g. if you look at https://docs.google.com/document/d/1HFUkAEE-pB-angVcYe6pf_-fVf4sCpOHKesUvfb8Grc/edit, then the only information about the document that you can still find is that it is created by JB Poline in 2015. The whole process of getting to v1.1.1 (right after merging BEP008 in 2018) is lost.

Discussion the content of the governance document might indeed be better done on the discussion list or neurostars rather than on github, but managing versions and hosting finished documents is imho better linked to the website, which happens to be on github.

Note that for initial discussions on a BEP google docs are still recommended (as per "extending BIDS" which links here). I do not propose to move away from that, just that the discussed-and-agreed-upon governance document is from now on maintained on github.

By the way, note furthermore that Google docs are not accessible in China. In our code of conduct we are explicit about "making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, ...". Although I do realize that "regardless ... level of experience" might be at conflict with github, I do think it is the better option of the two.

A few quick comments!

• if the docs can be parsed and rendered on the site, by way of that they should be indexed in Google if the site is. Of course this doesn't work for embedded content or PDF, you would need to retrieve the txt via url and then embed that.
• But if you are concerned about just finding a link, then embedding the doc or pdf into a page, given being surrounded with correct metadata, would be sufficient to index and find it (without knowing the url)
• resolved discussions cannot be read, this is definitely true. Google docs can show versions over time (and it requires edit permission, hence not working with the view only document from JB), but (afaik) you can't easily recover discussions. GitHub reigns strongly here!

The whole process of getting to v1.1.1 (right after merging BEP008 in 2018) is lost.

I think the tracking of changes still exists, but it's not some easy to export format (.git) and it requires more permissions on the document than View.

Discussion the content of the governance document might indeed be better done on the discussion list or neurostars rather than on github, but managing versions and hosting finished documents is imho better linked to the website, which happens to be on github.

If it's about linking to the website, it doesn't necessarily have to be hosted on GitHub too, there are oodles of ways to embed, or generate actual text content from an export url of a doc. You could even set up some regular CI to (on a nightly basis or other) run a job to retrieve the text, update a markdown file, and then push to GitHub pages. For example, all of the content of https://us-rse.org/blog/ is generated by parsing feeds for author blogs and then writing them to markdown and publishing each night. You implement once and then can go away, it works!

I think this is perhaps the biggest issue, of all that you've named:

By the way, note furthermore that Google docs are not accessible in China. In our code of conduct we are explicit about "making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, ...". Although I do realize that "regardless ... level of experience" might be at conflict with github, I do think it is the better option of the two.

If the API doesn't work either (e.g., a person in China that goes to a site that uses a URL to retrieve or embed text is blocked, likely) then that's a deal breaker here. I agree that using a technology that blocks anyone is the wrong thing to do.

Perhaps there is another solution - have you tried out hackmd? https://hackmd.io/ It's akin to Google docs but in markdown, and you can have everything from collaborative editing to linking to a GitHub repo so changes propagate. What I'm not sure about is commenting, but if you are editing a file from GitHub the discussion would likely be there.

Anyway, I'm fairly far from the communities here, but I hope that I can help out a bit!

closing in favor of bids-standard/bids-website#78