The fastest way to achieve a communication outcome depends on knowing what the right channel is to initiate an interaction.
A lot of time can be saved once you know what the best channel is to have a communication exchange. But as communication channels proliferate, it is harder and harder to figure out what your best option is to reach out to a company or a person. Is it better to reach out to a company on Twitter (or X as we are supposed to call it now), Mastodon, or LinkedIn? Does the company have a phone line for support? Who is responsible for evaluating new vendors? How can they be reached? And even more important: how do they want to be reached?
Interface discovery is a search and guess game
Today there are no explicit comprehensive standards that companies, governments, NGOs, and individuals can use to share their preferred interfaces. As a result, interfaces are published haphazardly: you often need to have some pre-existing understanding of how an organization works to be able to find out what is the best way to interact. This lack of clarity turns interface discovery into a search and guess game.
Without realising you have probably asked yourselves some of the following questions:
- Does company Y have an app? The only way for you to find out might be for you to search the app store, or to accidentally stumble on an obscure subsection of their website that links to their app listing in an app store.
- How can you get support for a product of a large conglomerate? On a product specific site? On a local brand site? Is it available in your language? When can you expect a response?
- What APIs does a company have available that third parties can use to automate some of these interactions? You might need to guess or search for the URL of their devportal.
To answer these and any other questions related to interface discovery, internet users have developed a range of intuitions. Maybe there is a contact page, maybe contact information is included in the footer. As a developer, you might go look for a developer portal, or try "developer.Y.com" to see if a company has published APIs. It might make sense to search Twitter, Facebook, or LinkedIn for a company presence. But watch out, you might end up on a parody account.
Interface discovery problems are accessibility problems
Interface ambiguity becomes even more troublesome if you look at it from an accessibility perspective.
How easy is it to find out about interfaces if you are interacting through a screen reader? Is the interface accessible to you if you are hearing impaired? Can you only decide the right interface if you can read text embedded in visual media?
Findability versus discoverability are important aspects of a great developer portal.
Developers have learned to expect that an organisation’s APIs will be published on its “developer portal”, which greatly improved both the findability and discoverability of these APIs. To get there though, the developer community had to evolve the socio-technical expectation that an organisation’s APIs should be available in an API catalogue on a developer portal.
What if we would learn from the API world, and treat all interfaces like we treat APIs: explicitly declare interfaces, and make them easier to discover.
That would not only save time, it would also create a pattern people or AI agents can use to start discovering and finding available interfaces. And by setting expectations about the format and location of interface documentation, it would also make it easier for people who are searching for ways to interact with your company in a specific media format.
If you are interested in getting updates about the initiative and/or you want to collaborate on a joint initiative, let us know here.
In the first part of the article series, Kristof Van Tomme explores why companies should develop their comprehensive interface catalog: how to explicitly declare interfaces, and how to make it easier to discover them.
Join us on the 3rd of April at AI The Docs virtual conference on the latest Artificial Intelligence tooling and best practices, specifically in API documentation and DocOps.
