Navigating a chaotic tech ecosystem can take away a ton of time from your team. Rather than delivering results, they may be looking for information. And that\u2019s true even for product managers.<\/p>\n\n\n\n
According to Stack Overflow\u2019s 2023 survey<\/a>, 49% of managers and developers spend more than 30 minutes a day answering questions. <\/p>\n\n\n\n All of these valid questions, but equally frustrating when you need to stop wasting time and ensure your project is on track.<\/p>\n\n\n\n Developer portals can solve this problem. Besides hosting API documentation and a catalog of your services, they have the added (and much-needed) benefit of streamlining your developers\u2019 experience. Despite this, you may still get some pushback from stakeholders.<\/p>\n\n\n\n Which is why we wrote this article. \ud83d\ude09<\/p>\n\n\n\n Here, you\u2019ll learn how to design a truly usable developer portal and how to prove its value to stakeholders.<\/p>\n\n\n\n Developer portals are a central hub of resources to access, understand, and test APIs. They provide quick access to API documentation, guides and tutorials, support forums, tools for testing, and any other resource that makes your developer\u2019s life easier\u2014at least when dealing with APIs.<\/p>\n\n\n\n The main benefits of a developer portal are:<\/p>\n\n\n\n Having a developer portal is better than being buried in email threads and scattered documentation.<\/p>\n\n\n\n To understand who uses developer portals, it\u2019s worth clarifying that there are two types: internal and external.<\/p>\n\n\n\n Internal developer portals<\/strong> are designed for the specific needs of an organization. These portals give access to internal APIs, documentation, and tools while improving collaboration between internal stakeholders.<\/p>\n\n\n\n External developer portals<\/strong> offer public access to APIs and resources for external developers, partners, and customers. This facilitates third-party integrations around your organization\u2019s services.<\/p>\n\n\n\n Here\u2019s how each audience\u2014internal and external\u2014uses developer portals in their day-to-day work.<\/p>\n\n\n\n Internal developers often spend a lot of time searching for information or tools. A developer portal is a centralized, accessible hub of information. Thanks to community features, they can ask questions to other developers besides that one coworker who helped them the first few days of onboarding.<\/p>\n\n\n\n In contrast, external developers have a more gradual learning curve. The use of developer portals allows them to access code samples and public resources that make development and deployment easier.<\/p>\n\n\n\n Internal technical writers have to maintain up-to-date documentation. But this can be a challenge when iterative development\u2014and the multiple changes that come with it\u2014is so important. However, access to collaboration and version control tools in developer portals solves this issue. <\/p>\n\n\n\n When it comes to external technical writers, a developer portal helps them create guides and tutorials that help external users integrate their services with your API. <\/p>\n\n\n\n Internal product managers oversee product development and its alignment with business goals. A developer portal gives them the analytic and monitoring tools to keep everything on track.<\/p>\n\n\n\n External product managers use your developer portal to access your API documentation and test your API to propose new solutions for their company.<\/p>\n\n\n\n This audience includes any other external stakeholders. Having a developer portal provides them with all the tools and resources they need to smooth out the integration of your services. It also promotes collaboration by offering clear communication channels and support.<\/p>\n\n\n\n Before deciding that a developer portal is the solution you\u2019ve been looking for, you should survey your developers to find out what they need. If you\u2019re going to make this investment and need approval from stakeholders, it’s better to have a series of requirements collected\u2014rather than saying that \u201csomeone in management thought dev portals were a good idea.\u201d<\/p>\n\n\n\n Moreover, if you\u2019re getting pushback from stakeholders, it\u2019s important to address their concerns directly. Here are some common concerns (and how you can counter them).<\/p>\n\n\n\n Stakeholders may think the costs of developing and maintaining a developer portal outweigh its benefits. After all, it\u2019s not always easy to prove an increase in productivity and engagement.<\/p>\n\n\n\n However, a developer portal can lead to significant long-term cost savings. According to Daan Stolk, co-founder of Alphadoc.io, 50% of support tickets<\/a> at one of his previous companies could have been solved with the proper resources in place. <\/p>\n\n\n\n Besides reducing onboarding costs, resources streamlined in a centralized hub means developers are going to spend less time trying to get information and spend more time well\u2026developing. Meaning the time-to-market for new features and integrations will be faster.<\/p>\n\n\n\n Some may argue that building or maintaining developer portals takes away resources from other critical projects. <\/p>\n\n\n\n The thing is, when you invest in a developer portal that provides a cohesive workflow, access to resources doesn\u2019t have to be subject to different tools and microservices. Your developer\u2019s brain power doesn\u2019t have to be spent on constant context switching or idle time. Instead, they have time to focus on higher-level projects with more cognitively demanding tasks.<\/p>\n\n\n\n This must be the most tedious reason why stakeholders don\u2019t like the idea of something new. <\/p>\n\n\n\n “We should have a developer portal that has all our resources in one place, plus a forum, plus our API documentation, plus…”<\/p>\n\n\n\n You can almost feel the collective reluctance to undertake yet another cumbersome project. Endless meetings, coordination, and troubleshooting is enough to make anyone’s head spin.<\/p>\n\n\n\n However, modern developer portals (like ReadMe \u2728) can provide a full suite of features, with minimal DIY work on your end. From data synchronization and API management to customization and security, these portals are designed to integrate with existing systems and workflows. Additionally, great customer service and guidance throughout the process guarantees a smooth transition.<\/p>\n\n\n\n Now, it all comes to this: should you build or buy a developer portal?<\/p>\n\n\n\n Building a developer portal<\/strong> involves your team developing a solution\u2026from scratch. The designing, coding, integration of API documentation, support, and interactive tools is up to you. However, you end up with a custom solution for your organization’s needs.<\/p>\n\n\n\n Buying a developer portal<\/strong> means getting a pre-built solution from a vendor. These platforms have ready-to-use features that include your API documentation, interactive guides, and support tools on a subscription or licensing basis.<\/p>\n\n\n\n To decide which option is better for you, let\u2019s go over the pros \u2705 and cons \u274c of building vs buying developer portals considering the following key factors:<\/p>\n\n\n\n A rule of thumb.\ud83d\udc4d<\/p>\n\n\n\n If you\u2019re a large company that needs to set standards for developers and has lots of resources (e.g. Google, Amazon, or Microsoft), building a developer portal may be worth the effort. On the other hand, small to medium-sized companies that want a cost-effective and less time-consuming solution should buy a developer portal.<\/p>\n\n\n\n Whether you\u2019re building (or buying) a developer portal, there are key features and best practices to keep in mind.<\/p>\n\n\n\n Let\u2019s start with a granular step-by-step on how to build a developer portal.<\/p>\n\n\n\n This is where you ask all the important questions and set the primary goals of your developer portal. <\/p>\n\n\n\n For example, who\u2019s your target audience? The first thought that comes to mind is developers. But are these developers internal or external? And what are their needs?<\/p>\n\n\n\n Here\u2019s a list of questions to help you steer in the right direction:<\/p>\n\n\n\n Make sure the answers to these questions are crystal clear. You don\u2019t want to end up with a portal no one uses.<\/p>\n\n\n\n To choose your technology stack, remember to ask yourself: are you building from scratch or buying a portal?<\/p>\n\n\n\n If you\u2019re building a developer portal<\/strong> where you have ownership and control over the design, functionality, and maintenance, Jekyll<\/a>, Gatsby<\/a>, and Backstage<\/a> are good options to start.<\/p>\n\n\n\n\n
What is a developer portal?<\/strong><\/h2>\n\n\n\n
\n
Who uses developer portals?<\/strong><\/h2>\n\n\n\n
Developers<\/strong><\/h3>\n\n\n\n
Technical writers<\/strong><\/h3>\n\n\n\n
Product managers<\/strong><\/h3>\n\n\n\n
Partners and businesses (External)<\/strong><\/h3>\n\n\n\n
Why do you need a developer portal?<\/strong><\/h2>\n\n\n\n
Concern 1: Cost \/ ROI <\/strong><\/h3>\n\n\n\n
Concern 2: Resource allocation<\/strong><\/h3>\n\n\n\n
Concern 3: Scope creep<\/strong><\/h3>\n\n\n\n
Building vs buying a developer portal<\/strong><\/h2>\n\n\n\n
Factor<\/strong><\/td> Building a Developer Portal<\/strong><\/td> Buying a Developer Portal<\/strong><\/td><\/tr> Budget<\/td> \u2705 No recurring subscription fees.
\u274c Higher initial development costs, and ongoing maintenance expenses.<\/td>\u2705 Lower initial costs, subscription, or license fees.
\u274c Recurring fees can add up over time.<\/td><\/tr>Time to market<\/td> \u2705 Up to you and dependent on your resources.
\u274c Longer development time.<\/td>\u2705 Quick deployment and availability.
\u274c N\/A.<\/td><\/tr>Customization<\/td> \u2705 Full control over design and functionality.
\u274c Customization can be time-consuming and costly.<\/td>\u2705 Standard features are readily available.
\u274c Limited ability to customize to specific needs.<\/td><\/tr>Support<\/td> \u2705 Custom support (almost immediate).
\u274c Requires internal resources and expertise for support.<\/td>\u2705 Vendor support included, access to expertise.
\u274c Dependency on the vendor for updates\/support.<\/td><\/tr>Integration<\/td> \u2705 Custom integration with existing systems.
\u274c Potentially complex and resource-intensive.<\/td>\u2705 Designed for easy integration.
\u274c Integration with legacy systems can be challenging.<\/td><\/tr>Scalability
<\/td>\u2705 Customizable to scale as needed.
\u274c Scalability depends on the initial architecture and ongoing resources.<\/td>\u2705 Typically designed to scale easily.
\u274c May incur additional costs for scaling.<\/td><\/tr>Ownership
<\/td>\u2705 Complete ownership of the codebase and intellectual property.
\u274c All responsibilities on your team.<\/td>\u2705 N\/A.
\u274c Reliance on vendor, no ownership of codebase.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\nHow to build a developer portal<\/strong><\/h2>\n\n\n\n
#1. Plan your developer portal<\/strong><\/h3>\n\n\n\n
\n
#2. Set up your infrastructure<\/strong><\/h3>\n\n\n\n