Deep dive into API on-boarding best practices

[audreykwr]

Problem statement

As the last content and design version was only a half a step up from lift and shift, we could do a deeper dive into best practices for this type of content that we could apply to make this an even better experience.

Open questions

• What other documentation exists that works well? We could ask engineers what references have worked for them in the past, check with other Nava projects and/or the Dev Ex group

• What specific areas of documentation do we want to key in on and how do we want to evaluate that? (i.e., do we have outstanding questions from the audit and design of the Programmer's guide like large tables of data?)

• What form should this research take so it is usable by others?

Acceptance criteria

• [ ] Collect other examples of API documentation

• [ ] Review backlog for previous ideas/needs

• [ ] Generate recommendations to apply to our API documentation

• [ ] Share with the team

[lizzieamanning]

@audreykwr @jillian-hammer before the start of sprint 65 (3/29) will you add any examples you came across in your work, as well as any specific questions/areas you would want this to cover? May pass on to platform design

[audreykwr]

Reference:

• pronovix.com has lots of good resources on developer portals and onboarding best practices: components, developer portal strategies, winners for API onboarding competition, 7 trust signals, improving API adoption, best practices, making advocates for your API, engaging users
• API style guide best practices
• paypal/braintree example - especially see sandbox which Avniel has mentioned
• another best practices take
• plaid API example
• best onboarding criteria description for devportal awards (some winners linked above as well)
• a whole bunch of open source APIs

[audreykwr]

Things to think about:

• Features we should build/content to add
• IA and categorization ideas
• Typical engineer engagement in onboarding process (i.e. how much personal support from an engineer is expected/average)
• How do products handle multiple APIs (as we most likely will at some point to some degree)
• How any of these products handle their technical documentation and instructions in balance with a more "general" audience for their product?

[lizzieamanning]

After reviewing with @jsutantio, we decided this is not a priority or the best fit for Platform design right now, so let's leave this in the WebEx backlog until we validate the guide with users and can reassess

[audreykwr]

In light of reorg and forthcoming priorities, backlogging continuing this more detailed work and combining this into more the high level overview in this ticket

[audreykwr]

I'll leave this up to the discretion of @jillian-hammer. I have kind of done this recently, but it's not bad to have this list of things to consider if we get deeper into improving API onboarding. CC @chris-kuryak