Edits to the About page

[Rikkm]

I've adjusted three typos in the About.md file. If I am correct, I now need to pull the site, recompile, and push the pages back up. If I am not correct, I am not seeing the edits in the active pages.

[ebeshero]

@Rikkm I went through this earlier this AM. Right now, the markdown files aren't being pulled into the HTML files for the outer shell of the website, but @mdlincoln I think is figuring out how to get the app to behave the way we want it to. @scottbot and I were corresponding about it earlier...

[scottbot]

Just to second what Elisa said, she and I both made a bunch of changes to the About and Method page, and I made several changes to the People page, that I suspect you'll want to update on the google doc so we're working on the same underlying text, @Rikkm.

[Rikkm]

I harvested the About yesterday before I sent out the google page link.

If you add edits to markdown, please update the google doc with your edits.

Also add a note to issues.

I’d prefer not to have to go hunting through GitHub memos and do sight comparisons.

Rikk

On Mon, Oct 7, 2019 at 09:05 Scott Weingart notifications@github.com wrote:

Just to second what Elisa said, she and I both made a bunch of changes to the About page, and I made several changes to the People page, that I suspect you'll want to update on the google doc so we're working on the same underlying text, @Rikkm https://github.com/Rikkm.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/FrankensteinVariorum/viewer/issues/5?email_source=notifications&email_token=AEVDDRQZOIB42WE45EVHXH3QNMXZTA5CNFSM4I54VOKKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEAQH7LA#issuecomment-539000748, or mute the thread https://github.com/notifications/unsubscribe-auth/AEVDDRVITKCKAQB7YT4P443QNMXZTANCNFSM4I54VOKA .

-- Sent from Gmail Mobile

[scottbot]

In line with your workflow and request, I've updated the Google Doc to reflect my changes to the people page. As I'm not the most recent person to update the method page, I'm not comfortable doing so, even though I did edit it yesterday. I've also updated the Google Doc to reflect my changes to the About page.

@Rikkm, quoting what @ebeshero said over email:

"I would like to see GitHub issues hold direct links to each of these Google Docs pages, so that we can use the GitHub issue tracker as our starting point for locating all of our edits."

"Google Docs should then be for complete overhauling and new drafting of pages. And a Google Doc needs to be retired and remade when the website version of the page is updated."

"It should help to think of Google Docs as a rough drafting area for new material. When we open and close issues to make small revisions for the website, part of the process needs to be checking if a live Google Doc is being edited too."

I agree with all of these for the least fragile possible workflow. Currently, only the "About" page is listed as actively under edits as an issue. In that case, a google doc of that page and that page alone should be linked to from the issue, for as long as it's under active edits.

As I understand Elisa's point, "Method" and "People" in this case, since they're not under active edits, should not exist as a google doc. If the others want to start working on them, we can pull them into a google doc, retrieving from the latest github version.

Right now, the only person in our team unable to edit the github markdown files directly is Jon. We can accept his suggestions in a google doc or, frankly, over email, and all the rest of us can just edit the markdown files directly.

I realize this is not the workflow as you currently conceive it, Rikk, but I think this will be more sustainable, allow for better institutional memory, generally aligns with best practices with respect to github pages, and (importantly) will mitigate against hit-by-a-bus scenarios and allow us to continue to edit the project using the same approach pretty much in perpetuity. That is, if we must continue to use Google Doc's for Jon's sake, I propose we shift to the approach outlined by Elisa, making this project github-first, gdoc-second, rather than vice-versa.

[Rikkm]

Thanks for adding.

I want to talk through this more, but not today.

The thing Elisa is forgetting is that some of our group are not comfortable with GitHub and will not be editing markdown, so having an ongoing page where they can add an edit suggestion will be necessary, if only to avoid losing requests that are made in email, as was the case this weekend.

On Mon, Oct 7, 2019 at 9:51 AM Scott Weingart notifications@github.com wrote:

In line with your workflow and request, I've updated the Google Doc to reflect my changes to the people page. As I'm not the most recent person to update the method page, I'm not comfortable doing so, even though I did edit it yesterday. I've also updated the Google Doc to reflect my changes to the About page.

@Rikkm https://github.com/Rikkm, quoting what @ebeshero https://github.com/ebeshero said over email:

"I would like to see GitHub issues hold direct links to each of these Google Docs pages, so that we can use the GitHub issue tracker as our starting point for locating all of our edits."

"Google Docs should then be for complete overhauling and new drafting of pages. And a Google Doc needs to be retired and remade when the website version of the page is updated."

"It should help to think of Google Docs as a rough drafting area for new material. When we open and close issues to make small revisions for the website, part of the process needs to be checking if a live Google Doc is being edited too."

I agree with all of these for the least fragile possible workflow. Currently, only the "About" page is listed as actively under edits as an issue. In that case, a google doc of that page and that page alone should be linked to from the issue, for as long as it's under active edits.

As I understand Elisa's point, "Method" and "People" in this case, since they're not under active edits, should not exist as a google doc. If the others want to start working on them, we can pull them into a google doc, retrieving from the latest github version.

Right now, the only person in our team unable to edit the github markdown files directly is Jon. We can accept his suggestions in a google doc or, frankly, over email, and all the rest of us can just edit the markdown files directly.

I realize this is not the workflow as you currently conceive it, Rikk, but I think this will be more sustainable, allow for better institutional memory, generally aligns with best practices with respect to github pages, and (importantly) will mitigate against hit-by-a-bus scenarios and allow us to continue to edit the project using the same approach pretty much in perpetuity. That is, if we must continue to use Google Doc's for Jon's sake, I propose we shift to the approach outlined by Elisa, making this project github-first, gdoc-second, rather than vice-versa.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/FrankensteinVariorum/viewer/issues/5?email_source=notifications&email_token=AEVDDRQTW4JV7RRXETXT7KTQNM5HTA5CNFSM4I54VOKKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEAQNCXI#issuecomment-539021661, or mute the thread https://github.com/notifications/unsubscribe-auth/AEVDDRRNUNYWFAYT3J5NJHTQNM5HTANCNFSM4I54VOKA .

[ebeshero]

@Rikkm I am not forgetting this. I am, however, suggesting you find a way to contain the editing process so that editing by Google Docs is not the main way we edit the website. Those who are not comfortable working in GitHub need to report to someone, probably you, to deal with edits. And you need to be comfortable making those commits to GitHub in a way that keeps up with the team and is aware of what's going on. This is kind of urgent and necessary.

Most of us do work in GitHub, and GitHub's version control system makes this the place to be working on edits in a sustainable and non-brittle way.

[ebeshero]

And if it were me, I would take this moment to teach people how to edit markdown files and eliminate Google Docs from the process entirely. Having edits streaming from multiple locations is less than acceptable. And dragging the team to have to use the technology of the lowest common denominator is basically unacceptable.

[scottbot]

Agreed with @ebeshero here. Currently the only person who can't be expected to edit the github is Jon, and he hasn't been using the google doc either, so I'm not sure if we'll be avoiding the email issue anyway. Happy to chat about it when next we see each other, @Rikkm.

With respect to Jon, I think it's fine not teaching him how to edit github pages, since his contributions will, I assume, be limited to certain moments of editorial milestones, rather than incremental like the rest of us.

[Rikkm]

Admittedly, it was Jon's emails this weekend that I have been responding to the most.

The google doc is my attempt to give him an option.

On the whole, yes, the rest of us should be able to edit the markdown, and update the issue tracker. The process of updating the site is not difficult, but it is a series of steps. I'll be pulling, recompiling, and posting tomorrow as a test of the documentation that I have in the office. (yes, in the future I'll also have it on my computer, not a paper version...it has a couple steps for me that aren't on the GitHub)

On Mon, Oct 7, 2019 at 10:11 AM Scott Weingart notifications@github.com wrote:

Agreed with @ebeshero https://github.com/ebeshero here. Currently the only person who can't be expected to edit the github is Jon, and he hasn't been using the google doc either, so I'm not sure if we'll be avoiding the email issue anyway. Happy to chat about it when next we see each other, @Rikkm https://github.com/Rikkm.

With respect to Jon, I think it's fine not teaching him how to edit github pages, since his contributions will, I assume, be limited to certain moments of editorial milestones, rather than incrementally like the rest of us.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/FrankensteinVariorum/viewer/issues/5?email_source=notifications&email_token=AEVDDRQXEPBNPXDTLRSCITTQNM7SLA5CNFSM4I54VOKKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEAQPMWA#issuecomment-539031128, or mute the thread https://github.com/notifications/unsubscribe-auth/AEVDDRUZT4FTPI6QLPSBZH3QNM7SLANCNFSM4I54VOKA .