When Describing Your Machine Learning APIs Work Extra Hard To Keep Things Simple
03 Aug 2017
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 straight up, 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. 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 meta data 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 always the ones that 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 description 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 5-10 hours a week looking through AI and ML API descriptions, and when I come across something that is clearly bullshit I don’t hesitate to flag, and push it back to the back warehouses of my research, keeping my time focused on the APIs which I can easily articulate what they do, and will also make sense to my readers.
Photo Credit: Bryan Mathers (Machine Learning)