In last month’s blog, I summarized some introductory concepts and tools for writing about hardware-related REST APIs, a journey I started myself a little over a year ago. To be honest, though, I didn’t make that journey alone. I have been the content strategist for a group of writers, who came at the challenge from various backgrounds.
As such I understand some – but not all – of the sticking points for some writers from some backgrounds. So I am curious, what other challenges do you or your team face when writing about a system-level or hardware-level REST API?
One example of a challenge that we faced as a team – documenting a REST API written by two geographically separate software development teams – was adhering to a consistent and common terminology for common concepts. And this was true of the developers, too, as they developed data types and parameters for the API.
I was amazed, as an example, how many different terms we in the high-tech world have for describing the capacity of a storage drive (be it HDD or SSD)…disk space, drive space, drive space allocation, storage space, storage allocation, repository, storage repository…and well, you get the idea. Difficult enough for one person (sigh, that would be me, the content strategist) to keep track of, let alone whole teams of people.
Let me know what kinds of challenges your team faces in your REST API journey. I will summarize them here in this blog space in a couple of weeks. I am happy to do so with or without mentioning names or companies.
Comment on this blog or send me an email at debra@dkconsultingcolorado.com. Looking forward to hearing from you!
DK Consulting of Colorado 