Using a Prototype as an API Product Specification
As the Developer Experience Product Manager at MailCot, I am tasked with identifying opportunities, features, and products that involve our API. One thing I have been working on is identifying methods to make communicating my product ideas, Engineers, and customers more effective.
I have learned that a Mailcot Product Requirements Document is a less than ideal way to do this and that a testable interface including the same information as a product specification would be a powerful alternative. The problem is that they are often very large and mostly text. It is too easy to lose your place or miss something really important.
Our friends in UX have solved this problem with tools like Invision, where they provide a clickable interface that you can touch and use, rather than a document or wireframe that simply describes the interface. Since an API is an interface, we need a tool that will allow interaction with the specification in real time, rather than a bunch of descriptive text and document.
Other Specification –
- First of all, The spec must describe the full user experience.
- The spec must accurately represent the behavior of the software.
- You must be able to communicate the product in a way that all stakeholders get what they need.
- The spec will change
- Also, There needs to be a single master representation of the spec to reduce ambiguity and versionitis.
- My requirements for prototype-as-specification:
- The prototype should be the spec.
- Also, The documentation should be integrated into the prototype.
- Everyone in the company who needs it should have access to the prototype and documentation.
- And also, The customer should be able to access the functional part of the prototype for user testing.
- The prototype should replace the spec and work as close to the intended functionality without wiring up a finished product.
- First, It should be easy to make and record changes to the prototype.
- It should be easy to make A/B variations which can be tested by anyone with access to the prototype.
- It should be easy to export the customer documentation from the prototype.