I’m spending a significant amount of time learning about machine learning APIs lately. Some of what I’m reading is easy to follow, while most of it is not. A good deal of what I’m reading is technically complex, and more on the documentation side of the conversation. Other stuff I come across is difficult to read — not because it is technical but because it is more algorithmic marketing magic and doesn’t really get at what is really going on (or not) under the hood.
If you are in the business of writing marketing copy, documentation, or even the API design itself, please work extra hard to keep things simple and in plain language. I read so much hype, jargon, fluff, and meaningless content about artificial intelligence and machine learning each day, I take pleasure anytime I find simple, concise, and information descriptions of what ML APIs do. In an exploding world of machine learning hype, your products will stand out if they are straightforward and avoid the BS, which will pretty quickly turn off the savvy folks to whatever you are peddling.
Really, this advice applies to any API, not just machine learning APIs. It’s just the quantity of hype we are seeing around AI and ML in 2017 is reaching some pretty extreme levels. Following the hype is easy. Writing fluffy content doesn’t take any skills. Writing simple, concise, plain language names, descriptions, and other metadata for artificial intelligence and machine learning APIs takes time and a significant amount of contemplation regarding the message you want to be sending. The ML APIs I come across that get right to the point are the ones that always stick around in my mind and find a place within my research and storytelling.
We are going to continue to see an explosion in the number of algorithmic APIs, delivering across the artificial intelligence, machine learning, deep learning, cognitive, and other magical realms. The APIs that deliver real business value will survive. The ones that have simple intuitive titles and concise yet informative descriptions that avoid hype and buzz will be the ones that get shared, reused, and ultimately float to the top of the pile and sticking around. I’m spending upwards of five to ten hours a week looking through AI and ML API descriptions, and when I come across something that is clearly bullsh*t, I don’t hesitate to flag it and push it back to the back warehouses of my research. I keep my time focused on the APIs that I can easily articulate and that will make sense to my readers.