(Hint: Success in both is all about your team’s communication and collaboration)
“The API Product Manager role is probably the most essential role to creating that collaboration and that communication across your API team,” – Wil Kirwan, Senior Product Manager at Stoplight.
July at Stoplight is dedicated to collaboration within your API team–establishing processes, involving stakeholders, and the tools that help you collaborate better to create quality APIs. One of those roles requires essential, well-established collaboration to succeed: the API product manager.
We spoke with our Senior Product Manager, Wil Kirwan, to better understand how API product managers can utilize collaboration and what good collaboration looks like amongst their teams. We may have even dropped an easter egg or two on some exciting new collaboration features coming to the Stoplight product later this year, but you’ll have to read on to find those!
Dungeons & Dragons, More Like Developers & Decision Makers
“Product managers act as force multipliers, meaning that bad ones exacerbate problems through bad communication, but a good one can easily shoot the productivity of the entire team through the roof,” shares Wil. 
Wil compares the work of a Product Manager to that of a Dungeon Master running a DnD campaign (if you don’t know what DnD is, you should look it up, it’s fun!!).
Much like the Dungeon Master, the PM has to go through intense work to describe a problem. If they describe too much, they run the risk of the rest of the campaign party (i.e., your developers) focusing on the wrong thing. Being a product manager is the same way.
“The balancing act for a product manager is finding the right amount of information to give the team to solve the problem–no more, no less. In DnD, if the DM tells the party that there’s a pipe on the wall in the corner, there is a good chance that will be all they focus on, even if it’s not key to solving the problem or advancing their campaign. The same can be said for what you share with your developers,” shares Wil.
Communication with developers and product managers must be a fine line because, with too many details, a developer will focus on the wrong details when trying to solve a problem. Too little information and they won’t be able to envision what you’ve appropriately proposed.
What Does Proper Collaboration for an API Product Manager Look Like?
API product managers define the ‘what’ and the ‘why’ around a problem, ensuring that clarity and understanding are rooted throughout the entire API design process. API product managers must be good communicators and keep collaboration and cohesion top of mind for their developer team.
Product managers also have to be responsible for not just ensuring synchronization across their internal team, but also are the main conduit for customer collaboration and getting that feedback to the internal developer team.
“If you have that upfront clarity for your developers on what your customers want, you eliminate dysfunction. The nightmare scenario for every developer and scrum team is when we have to go back and undo something we already coded because we didn’t communicate well enough the first time,” shares Wil.
Good Communication
So if good communication is a necessary part of the API Product Manager role, how do you practice it? Solid communication across your team manifests as concise, consistent information and regular check-ins with all stakeholders involved in the design of the API.
When a PM is operating under a level of poor communication, it leads to second-guessing, designs that have to be redone, and a developer experience that is subpar at best for your internal teams.
“One of the worst things that can result from poor communication between an API Product Manager and your developers is the introduction of breaking changes; that’s often a worst-case scenario. Whether it’s a text field that should’ve been a number, a variable mistype, or a field gets omitted–miscommunication can create various breaking changes, and that likely means changes to applications will need to be made,” shares Wil.
It’s also important to note that poor communication between PMs and developers won’t just impact the internal team but will also have implications downstream. Negative network effects down the line can be a pain in the neck for all to deal with, especially for your customers.
Have Empathy
We know this is a common theme we reiterate time and time again here at Stoplight, but it rings true even in the collaboration process. A good API Product Manager will emulate empathy and remind their developer team to do the same, especially when working with customers.
As the product manager, you must be empathetic to both sides of the conversation (your internal stakeholders and your end users), and collaborating with all sides is the key to a successful PM.
Get It In Writing
Always document processes, conversations, and decisions to ensure great collaboration and communication across teams. In today’s modern world, there is no excuse not to have it in writing somewhere. And–even better if that is in the same place every time. Don’t just keep a notes app on your phone; have an outlined process of where all documentation ends up, whether your team uses Slack, Notion, Google Docs, etc.
“For new product managers especially, I really push on having GOOD habits of creating a doc for your team from all team meetings and immediately putting it in your Slack channel or whatever tool you’re using so that it doesn’t get lost. Doing this consistently is key,” shares Wil.
Wil emphasizes that having a ‘decision doc’ for every significant technical decision his team needs to make internally has improved collaboration and communication exponentially. That way, you always have proof to refer to and an understanding document of why you made the previous decisions that you made based on the information you had at the time. It saves time down the line should your team have to revisit those conversations.
Get the Right Tools for Collaboration
Once you have the dedicated, self-directed team in place, deciding on what the main tool(s) you will use for collaboration is necessary. The right toolset will empower your developers to communicate regularly and effectively with their API product manager, ensuring all are on the same page.
“That collaboration tool needs to be ingrained in the culture of your team itself. For example, our team internally utilizes Figma for design and Confluence for building around the API,” shares Wil. “I’m excited because our roadmap will eventually add Comments directly into the Stoplight Platform. I think that will fill a nice, organic collaboration niche within the tool around API design. Then, folks can collaborate directly in Stoplight instead of needing a variety of tools!”
Here are a few of our favorite examples of collaboration tools we utilize here at Stoplight for our product and engineering teams:
“In the 2+ years of the pandemic, we all had to rapidly adapt new communication and technology options, which is great because it means there’s no lack of collaboration tools out there,” shares Wil. Just like Dungeon Masters needs their trusty dice and other tools, an API Product Manager needs collaboration tools that will aid them in their journey of API creation.
Collaboration Within Stoplight
Speaking of exciting things to come within the Stoplight product (check out our roadmap where you can see what’s next and make suggestions), we’ll throw another sneak peek our users’ way by mentioning another carrot. Later this year, Stoplight will be launching Comments and Discussions, which allow for further collaboration within the tool. Users will be able to tag other users, inviting them into the Workspace immediately and showing users feedback in live time! Stay tuned for more to come on that in the coming months. Keep an eye on our roadmap for more.
“As I think about Stoplight and the way we look at the role of an API PM, it’s a lot like a dungeon master where information is brought together in a centralized way for various team members, and your job is to make the collaboration process as easy as possible,” shares Wil. “We know that the API teams who have that strong point of collaboration often outperform the ones that don’t, regardless of if that team has higher-skilled developers.”
With collaboration features such as Comments and Discussions, product managers, developers, business leaders, and API program managers alike will be able to work together in real time, utilizing a design-first approach to build their APIs. It will allow for easy design on the fly, incorporating quick feedback from across the business and from customers to ensure continuity and seamless development.
If you’re looking for ways to collaborate in Stoplight that are available today, here are a few things to get you started:
- Connect your source control to Stoplight to keep that in sync
- Keep your docs updated regularly (tools in the Stoplight Platform or our open-source documentation tool, Elements, is a great place to start there). In the D&D world, Dungeon Masters would look at this as their rulebook for the campaign. In our world, API Product Managers look at the documentation to serve as their rulebook.
- Have new team members view your current workflow and docs with fresh eyes, pointing out things that don’t make sense and may need revisiting.
- Utilize the Workspace Groups feature to group projects together by theme, business need, and internal or external use.
- Collaborate over Style Guides to create consistency and standardization across your whole program
- Invite new team members to your Workspace to get them plugged in
Whether you’re a Dungeon Master or an API Product Manager, there’s a lot to be said for good collaboration and communication across your team aiding in the success of your API program.
