General feedback

[miaojiang]

• 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.