I forget what a great vehicle API Evangelist for sub-tweeting conversations that I see occurring across the API universe. I made a career out of doing this for the last decade, taking a moment to anonymize and generalize conversations and realities I witness across the space, writing up here as a story, and using them to help educate and bring awareness to the API universe. One that I am finding myself doing more storytelling about is about the transparency and communication necessary when building API specifications. I wrote about this last week on the Postman blog showcasing the radical transparency of the AsyncAPI community, and it is something I want to continue highlighting because it is very difficult to get and keep people’s attention in this digital world.
You have to be transparent and open by default when you are building API specifications. I don’t say this just for some hand wavy ethical stance, but it is critical to ensure your community is informed and aware, and keep people from gumming up the works with their lack of understanding and obstruction to forward motion. While doing the hard work of moving any open source specification or tool forward you find yourself inundated with drive-by feedback from folks, and if you aren’t extremely clear about how folks should be tuning into the conversation, and make every action public across multiple channels, this feedback will be even more uninformed than it has to be. People just don’t have time in their busy days, and most people aren’t equipped to see the work that is already occurring within an open source community. So when they do come across a single issue, meeting, or other relevant conversation, the likelihood that their feedback will be uninformed and not in alignment with the community is pretty high.
People, especially men excel at stepping into a conversation wildly unprepared, uninformed, and oblivious to the hard work volunteers and the community are already putting into something. Personally, I try to spend as much time listening and learning before I begin offering to help or provide constructive criticism about where to go next. Even then there is a high chance that my feedback will be received in a hostile way by embattled community managers and stewards, which don’t always realize how their defensive stance can push away well-meaning folks who are stepping up. I get it. It isn’t an easy place to be, and it can be hard to separate drive-bys from those willing to role up their sleeves and get things done. It is tough to see the momentum that exists within an open source community, and when you have something very abstract and technical like API specifications, it gets really hard to make sure we are all on the same page.
This reality is why I am open by default in what I do with API Evangelist, and why I support the AsyncAPI community in their radical transparency. I understand that this level of transparency isn’t something everyone is used to, or equipped to do, but it is something that can really help keep the community informed, and attract new members. It is a real bummer to spend 20 hours doing some volunteer work within an API specification community, write a blog post about it, tweet it out, share it in multiple Slack channels, only to have folks tell you that you need to work harder to share what is going on, or suggest you do something you have already done. I get it. We are all busy. I miss a lot of what is happening the more I find myself buried in work. This is why we have to be radically transparent by default and overly communicate whatever we are doing around API specifications, because there are a group of people who face this reality, but for some reason are unable to see and understand the work that is happening within a community, and take a moment out of their to get up to speed before they speak up.
