Re: 'APIM - 03 - Deployment'

[jamietanna]

Feedback on 'APIM - 03 - Deployment' (https://alphagov.github.io/data-standards-authority/guidance/apimanagement/APIM-Deployment.html)

Some content suggestions:

-Your assurance assessment programme should make sense for the teams who need to go through it. If development teams find the assurance process too rigid, they might try to avoid it, which will weaken your organisation’s governance model. Think about how you can make governance as light touch as possible, and how you can make it a positive experience for product teams. If review sessions have good outcomes for teams and provide them with useful feedback, other teams are more likely to submit to it. As a result your governance model will be more successfully embedded into organisational culture.
+Your assurance assessment programme should make sense for the teams who need to go through it. If development teams find the assurance process too rigid, they might try to avoid it, or bundle multiple sets of changes into a single release to reduce their overhead, which will weaken your organisation’s governance model.
+
+Think about how you can make governance as light touch as possible, and how you can make it a positive experience for product teams. If review sessions have good outcomes for teams and provide them with useful feedback, other teams are more likely to submit to it. As a result your governance model will be more successfully embedded into organisational culture.

 Testing is the process of making sure the APIs function properly, and is more likely to be an automatic process which validates the code. Testing should be an ongoing process, and regular validation of the API should be part of a monitoring scheme.
 
 Usually, testing is done by an automated tool against the specification, sometimes known as the contract. Contract testing in its simplest form includes:
 
 - checking the specification against internal policies to make sure that APIs submitted to the developer portal are compliant with internal standards
 - checking the API to make sure its responses match the specification and that deployed APIs are behaving correctly in production
+- checking the API to make sure requests matching the specification work correctly, based on (automated) input from consumers of the service

+Note that this is usually an effort on top of the regular testing process that teams will be performing, such as unit testing.

-You can also use your developer portal to gather internal metrics about your API programme. For example, you might want to measure how quickly developers are able to set up a test version of an API. This is sometimes known as “time to live” or “time to 200” and is a useful metric to measure how easy your API is to integrate. It can also help you identify where there might be pain points for users.
+You can also use your developer portal to gather internal metrics about your API programme.
+
+ For example, you might want to measure how quickly developers are able to set up a test version of an API. This is sometimes known as “time to live”, “time to 200” or “time to first call” and is a useful metric to measure how easy your API is to integrate. It can also help you identify where there might be pain points for users, and what you can do to improve the onboarding experience.

-You can use the GDS Technical Documentation Template to generate accessible documentation pages from simple Markdown files. It’s mainly used for standalone documentations sites (for example GOV.UK Pay’s API documentation). The Tech Docs Template is a Middleman template, so if you’re using an API management tool, you might be able to build the template into your generated documentation..
+You can use the GDS Technical Documentation Template to generate accessible documentation pages from simple Markdown files. It’s mainly used for standalone documentations sites (for example GOV.UK Pay’s API documentation). The Tech Docs Template is a Middleman template, so if you’re using an API management tool, you might be able to build the template into your generated documentation, or utilise [the various Open Source options for documentation generation](https://openapi.tools/#documentation).