Build What’s Next: Digital Product Perspectives

Building Better Developer Portals: From Design to Support

Method Episode 17

In this insightful episode of Build What's Next: Digital Product Perspectives, API expert Jeff Nibler and Michael Gray, Head of Engineering at Method, share their extensive experience with developer portals and API platforms. The discussion covers the transformation of developer portals over the past 5-7 years and crucial elements for success.

Key points discussed include:

  • The importance of discoverability and user experience in developer portals
  • Different approaches for internal versus external developer portals
  • The evolution from viewing APIs as utilities to seeing them as products
  • Building effective support structures for API programs
  • The role of sandbox environments and documentation in developer success

Key insights shared:

  1. Focus on Developer Experience:
    • The importance of clear, human-readable documentation
    • Making APIs discoverable and easily accessible
    • Providing interactive consoles and sandbox environments
  2. Internal vs External Portals:
    • Internal portals focus on avoiding API duplication
    • External portals require additional polish and marketing elements
    • Different support structures are needed for each type
  3. Support Structures:
    • The need for specialized API support teams
    • Finding the right balance between developer expertise and support efficiency
    • Integration of support ticketing within the portal
  4. Documentation Best Practices:
    • Making content accessible to both technical and non-technical audiences
    • Using a CMS for efficient content management
    • Implementing effective tagging and search capabilities

The episode concludes with practical advice for organizations starting their developer portal journey, emphasizing the importance of fundamentals like solid API design, security considerations, and developer experience.


Episode Resources:

  • Best practices for API documentation
  • Developer portal platforms and tools
  • API design guidelines
  • Support team structures
  • Content management systems for developer portals


Episode Highlights:

  • [05:48] Discussion of developer portal evolution
  • [17:25] Sandbox environments and developer experience
  • [24:53] Internal portal considerations
  • [29:31] Support team structures
  • [34:14] Starting a developer portal journey


Key Quotes:

  • "The golden rule for me on this topic has always been as much DIY as absolutely possible, everywhere possible."
  • "The struggling moment that causes them to create a space. Because if they don't ask a question, there's no space in their brain for them to see your product."
  • "I want my API people talking to your API people, and that's great, but I don't want them talking to my API developers because they're busy."