I have the first draft of a developer portal ready for an API project I am working on, and before I move forward polishing it too much I wanted to step back and think about the goals behind the launch of this API portal, and the intended audience I'm targeting with its operation. I do not want this landing page to just speak to developers, I would like it to speak to as wide of an audience as possible.
This particular API portal is meant to support the development of human service websites, mobile, and other applications in the Miami area. I do not want to scare off the "normals" with the home page. I want to make sure the language I use speaks to API newbies, while also giving experienced developers what they need to get up and running and solve any problems.
While not all APIs will be targeting this wide of an audience, but when it comes to human services at the municipal level, we need to be reaching as many people as we can. I am looking for the developer area to speak to journalists, policy makers, analysts, interns, and even just data curious citizen activists. I think I have all the essential building blocks of an API portal present, things like getting started, documentation, and support, now I just need to polish the titles, text, and other elements so that they are as plain English as they possibly can.
As I do this I shouldn't be assuming that a user will ever be actually integrating with an API, they might just need to understand the concept, what is possible with the API, and then engage with someone else who will actually be doing the technical heavy lifting. I'm going to have to put down the technical work on this project for a day or so before I can write content that speaks to non-developers--I am just too close to the code right now. I want to be able to craft a coherent explanation of the importance of this particular API and incite someone to walk way thinking about what is possible with a human services API.
