zinc-collective / convene

An Operating System for the Solidarity Economy
https://convene.zinc.coop
Other
56 stars 19 forks source link

📝🧹 `Marketplace`: Updates Stripe docs in README #1604

Closed rosschapman closed 10 months ago

rosschapman commented 10 months ago

Took a quick-ish stab at expanding the docs to give devs a stronger helping hand when setting up payments for Marketplace. Also note that I created a new /docs dir so that doc-related assets could live separately from code.

What do y'all think?

zspencer commented 10 months ago

It’s a bit hard to see what changed with the move and the edits; mind unwinding the move for now? We normally use README for the “here’s the bare minimum” and docs for breaking out other useful stuff

anaulin commented 10 months ago

Just having the move be in a separate commit from the changes would be enough to see more clearly what has changed, I think.

KellyAH commented 10 months ago

It’s a bit hard to see what changed with the move and the edits

I agree. But it's ok. I have not finished setting up my local dev environment for the Stripe workflow. So this is a great opportunity for me to test out the readme changes.

My local is broken right now. So I could only review the text for this PR. Once I fix my local, I can actually run through the steps to really test this doc. Do not let that stop you from merging this.

@rosschapman ❤️ TYSM for the very detailed and friendly written doc! I am new to Stripe so it was very reassuring to read, easy to understand, and the "turn on Test Mode" screenshot was very helpful.

rosschapman commented 10 months ago

Feeling appreciative of all the feedback!

@anaulin @zspencer normally I would separate the commits sequentially to make reading the diffs easier. Good reminder. I've now pulled out the local development section from the primary README as @zspencer suggested. I like that. It also diffs better.

@KellyAH seems like you got your local env working well enough to step through the new instructions!? Awesome, thorough QA, and very helpful suggestions, indeed. I believe I've responded to all of them. Let me know if you want to keep looping on anything. Also since its docs, I'll just merge and we can keep refining as needed.

@zspencer I hear you on these:

What parts of the docs are likely to go "out of date" by virtue of us simply improving our UX? (For example, setting the webhook secret via the UI vs via the console)

What parts are duplicious of Stripe (For example, could the "turn on Test Mode" could be a link to https://stripe.com/docs/test-mode?)

The eternal conundrum. Good docs certainly increase maintenance burden. Let's see how quickly these go stale? And how much appetite the team has for maintenance work? I'm still learning how to be in the slipstream of this open source work and where to get the best bang for the buck.

Also, I'm ok with trading on some overlap (added dependency), so a cow path exists; even if narrow, and shared (coupled) with Stripe. If, again, you'll allow a little wait-and-see.

zspencer commented 10 months ago

dwight-yes