Connecting GitHub and Google Docs Workflow

[pavlenex]

Introduction

For our current workflow on the Design Guide, we use GitHub as a core software. However, for most people who aren't developers, GitHub comes as something hard and complicated. While we can discuss whether GH is more complex than Figma (looking at you @GBKS 👀 😄 ), it's obvious that there's an interesting disconnect between contributors working via GitHub vs. working via Google Docs.

Goal

This discussion aims to try to come up with a solution to disconnect between GitHub and Google Docs.

Benefits

As the end-result, the unified workflow should allow us to:

1. Have more eyes on the existing PR's
2. Be in better sync regarding the progress of the work being done
3. Be more opened to contributors who aren't ready just yet to learn GitHub

How to reach the goal

1. Get feedback on whether or not the community and contributors feel this is worth proceeding with.
2. Brainstorm on ways to achieve this (Integration, having a centralized place (GH Project) that links to all relevant documents, pull requests, etc.
3. Experiment with few different approaches and see which one works as a test
4. Implement the process into our workflow if it proves to be effective enough.

Google Doc version of this discussion

If you prefer Google Doc feel free to leave feedback that way.

[GBKS]

I think it's more of a process thing. Early on, when content is rough, it's much easier to mold and get feedback on in a Google Doc. You can easily share a link, others can click and leave a comments super fast. You might just work in a small group of a few people you know and trust with edit access. As the content ripens, there comes a point where it's time to move it to Github. You may want a larger group of reviewers, so you need the stricter review tools Github provides. Feedback becomes more focused, and you work towards a solid version that can go live. At the same time, you want to see the content in the framework of the website, so you can tweak images, layout and visual formatting details. Editing becomes more complicated in markdown and you need to be comfortable working with Jekyll snippets and Github commits.

So I don't think there's a problem per se with people using different tools at different stages of projects, whether it's Google Docs, HackMd, Miro, Figma, Blender, etc. I personally try to use the right tool at the right time for the task at hand, being aware that the end-result is something on Github in the form of markdown and images.

One of the problematic things is making the switch over too late, underestimating how your view of your content changes once you see it in the framework of the site. You realize all kinds of details that need tweaking that just weren't visible before. But I think that becomes easier after you've gone through the process of publishing once.

Was this triggered by a specific situation?

[pavlenex]

Indeed this has been triggered by a few situations and by talking to a few people from the community, understanding how they work, why they work a certain way and why they feel there's a disconnect in the process.

I also believed it's a process thing and that different tools are used in different stages, but the more I think about it, the more it seems like a barrier.

I've opened this to figure out how we can improve the visibility of the workflow/progress on both ends and not change the workflows.

I'm wondering if there should be storage where we can dump different documents, a dedicated bot that can post on Slack info on both ends, or if it's needed some deeper integration between these two.

For example, I am completely unaware of what's going on beyond GH, whereas people working on GD documents aren't really aware of the pull requests on GH that need reviewing.

While the final submission is through GH, I think we're missing potential inputs from Designers, people who don't really use GitHub but are our target audience.

I'm hoping to learn how we can implement these distinctive workflows and make it easier to understand the progress on both ends.

One recent example is a review of a Principles PR posted on Slack, had a video explaining it, and more importantly, had a preview website link. The feedback (which was quite in-depth) was provided through the Slack thread.