Did you play ever play the “Telephone” game? The game where one person tells a secret to a person on one side and then that person passes the secret on to the next person. The funny thing happens and the secret is usually changes from the initial secret. When we build APIs the documentation which includes the text, graphics and maybe videos I argue is more important than the underlying technology API. The documentation provides context and a story for how and when to use the API but how are you validating that your API documentation matches the intended use case and provides inspiration for growth?
Some would make the argument that if you conduct user testing on your APIs and update from the feedback then you APIs are rock solid. Here I would use my Second City training and “Yes and” that statement. I would agree that yes user testing and validation will make some great APIs. On top of that I would also argue for the need to constantly conduct these tests and sometimes with the same set of users. The tests from a user who has seen an API for the first time and a user who has worked with an API for a couple weeks is different.
The needs and context are different of user change over time. For example, I loved my television when it first arrived. Now after a few years of use I am annoyed by the remote that does not work with my other components. The picture I find has faded in certain spots. Would I buy this television again most certainly because I still love it but I need some modifications to some components. Just like the the APIs my team and I build. I know that they are great products and I know there are faults. I need tests to be conducted with users who have never seen the product and users who have utilized the products for a few months. The feedback provided is going to tell me what is great about my APIs and what I need to prioritize in my backlog to improve. The tests will also take into account competitors, unknowns shifts in technology, the economy or other factors that my team might not be able to control.
I would further make the statement that these tests need to be conducted by more than the product or ux teams but by the engineering teams as well. This first hand feedback will provide the engineers who are building and taking part of designing the APIs more input and push the product into new heights.