miaojiang
commented
3 years ago - General feedback
- Consistently use "monetization" across the repo, currently both monetization and monetisation is used :)
- I think the flow is still a bit disjoint and might be confusing (I actually got lost). To me a reader should follow the below flow and we need to restructure the content a bit:
- Start with readme.md to understand the purpose and scope of the repository with a table of content
- Read the two high-level docs to get an overview
- Read an overview of integrating APIM with Stripe (i.e., What is Stripe, how Stripe's product map to APIM product, architecture diagram, consumer flow)
- Ready to deploy the sample, read and complete the pre-requisites
- Follow instructions to deploy the project
- In readme.md
- I suggest providing a full table of contents with purpose of each doc and where to start
- In the diagram, I suggest change "App Service" to "Billing App" or "Custom Billing App" to be consistent with other diagrams
- I would suggest moving pre-requisite to stripe-deploy and adyen-deploy to make readme.md concise - readme.md can just cover the purpose of the repo, table of contents. We already have a pre-requisite section in those docs.
- Adyen and Stripe docs
- It's unclear what are "pricing model" vs "revenue model". Are they APIM products vs Stripe products? The explanations in the doc did not help.
- deployment-details.md
- This doc is in the repo but not referred from any other doc.
- advanced-steps.md
- The doc says "If you want to make modifications to the infrastructure templates, you will need to run a build script in order to generate a new ARM template output for deployment." - I am not sure does the build script generate ARM template for APIM? or the Billing Portal? Please expand a little.
- how-APIM-monetisation.md
- "Delegation" is a key feature to make the integration possible. I think we should expand on that section a little bit assuming users do not know what "sign up and the subscription stages of the process" means at this point. We touched on that topic a little in the "API Consumption" section.
- If structure of the repo is updated, then the link in the last sentence of this doc will need to be changed as well.