If you’re thinking of setting up a developer portal for your software development teams, now is as good a time as any. Developer portals can help your teams start building new projects in a more efficient and streamlined manner. With all the necessary information about available development tools, development environments, service ownership, external APIs, and SDKs present in one place, developers can follow a more systematic approach while building new tools and products.
Developer portals should be seen as a long-term investment that helps make software development quicker and easier for all future projects. While they need to be audited and maintained regularly, developer portals are tools that usually boast a longer usage cycle and can be used extensively by IT teams across the organization. Once set up, they are useful to both developers and engineering leadership in accessing the information they need to make decisions at various levels of the development process.
This makes it all the more important for you to be methodical and meticulous while building a new developer portal for your software engineering teams. The high importance and operational utility of these portals warrant greater attention to detail while building them. We at Cortex recommend using a systematic, step-wise approach to ensure storage and display efficiency are maintained and the veracity of all data included in the portal is kept in check.
But first, let’s understand what a developer portal exactly is and how it can help organizations switch to quicker, more efficient, and better-documented software development processes.
What is a developer portal?
Developer portals are centralized repositories that contain all the information that is relevant to software development teams. They act as consolidated points of reference where all developers (both internal and external) can clear their doubts and obtain necessary details about the development environments and tech stack they currently work with or are expected to be working with in the future. Developer portals can include specifications, key parameters, and other performance and technical information about various aspects of the software development process. These include microservices, the APIs and SDKs that connect them, their dependencies, ownership status, the resources they use, and so on.
Traditionally, developer portals were made to help development teams familiarize themselves with the external APIs that they would use to build modules of an internal project. These portals act as extensive repositories of information that provide API teams access to support in the form of FAQs, how-tos, system specifications, and other technical information. Companies publishing these APIs often have external developer portals readily available on their website as a good customer service measure to promote the use of their APIs. External API-centered developer portals continue to be the most common form of developer portals used today.
However, a new kind of developer portal is now gaining popularity because of its high operational utility and ability to streamline and optimize the development process itself. Internal developer portals are used by companies as reference tools that provide development teams with information about the development tools and environments they are expected to be working with. Much like API developer portals, internal developer portals are vast repositories of system information that function as a common point of reference for all development teams working on internal projects. Internal developer portals help to make important information instantly accessible to developers, making it much easier for them to use documentation and troubleshoot while writing code. These portals also make it easier for teams to track the ownership of microservices and their dependencies, which determines the hierarchy you must follow while solving a problem related to a specific microservice.
Internal developer portals function as a one-stop destination for virtually any information that a developer or manager needs to access about the microservices architecture they are working with. What would otherwise be information stored in disparate, hard-to-access locations is centralized in a repository that can support team operations in a significant manner. Let us now look at a few reasons why setting up a developer portal is one of the best steps you can take to improve the developer experience.
Why do you need a developer portal in 2023?
Industry veterans will tell you that at some point, setting up a developer portal will become the obvious next step in refining your teams’ development workflows. Although it is not a task quickly completed and checked off the to-do list, it is an investment that is worth the time and resources that you will pour into it. Access to information is at the heart of any internal developer portal, but here are a few more reasons we recommend considering putting one together.
Developer self-service: Developers must be given the opportunity to spend time doing what they are good at, i.e., developing software. Unfortunately, the reality is that they spend too much time looking for the documentation of an API or identifying the owner of a microservice. Easy access to any information they may need about the architecture they are working with not only saves them time and effort but also enables them to be more independent and engage in “self-service” to get what they need.
Monitor microservice health: Monitoring and observability are key practices to ensuring that your software infrastructure is healthy and reliable. Having a dedicated developer portal that keeps track of the status of your applications is instrumental in this regard and can help streamline on-call and incident management efforts. It is a way for developers to stay on top of the software development process and make sure that end-users do not experience significant issues with the software.
Architecture complexity: Monolith applications have their faults, but are arguably simpler than microservices architectures in some ways. The decentralization of cloud-based, microservices architectures lends itself to a certain level of complexity, which can quickly turn into a nightmare to manage if not kept in check. An internal developer portal can act as a saving grace as it keeps the system organized, no matter the level of complexity, which plays a significant role in its accessibility to developers and managers. As your teams’ needs evolve and the architecture grows more complex, there is likely to come a point at which not using an internal developer portal is no longer an option.
Knowledge sharing: Internal developer portals should not be underestimated when it comes to their ability to facilitate internal knowledge sharing. Autonomous team structures are prone to developing siloed knowledge, which can prove detrimental to the pace at which the organization grows, and its efficiency on a day-to-day basis. By encouraging consistent and organized documentation, internal developer portals boost knowledge sharing endeavors and practices across teams.
Consistency across teams: One of the potential pitfalls of having autonomy built into how teams are structured in an organization is the development of idiosyncratic knowledge and workflows. If teams begin to adopt wildly different methods, for instance, it is a mammoth task to then coordinate and align them in a way that two teams are able to work with one another or build on top of the other team’s work. For this reason, managers need to drive adoption of certain standards and best practices that allow them to maintain a level of consistency without compromising on the teams’ autonomy. Internal developer portals are beneficial in enacting and encouraging such consistency across teams.
To reiterate, we recommend taking a systematic approach to setting up a developer portal which involves treating it as a project to be completed in multiple stages. Here are the different stages involved in setting up a developer portal and what makes each of them so crucial to the overall process.
Setting up a service catalog and allocating service ownership
Setting up a service catalog is akin to charting out a blueprint of a project before starting any work on it. As the term suggests, a service catalog is a simple, centralized database that lists out all the IT service offerings that are currently available to your internal developers. Service catalogs are made to give developers, project managers, and other stakeholders in the development process a quick snapshot of what the digital systems of the company contain at any given point in time.
Information about all the projects that the company is currently running or has shelved for any reason is collected at the start of building a service catalog. This includes everything from the services, microservices, and APIs each project uses to their ownership, performance, and business capabilities. Once collected, this information is sorted and tagged with service-specific metadata which helps store it in a structured format. After this is done, proper service documentation and runbooks are added to the service catalog. Runbooks are incredibly efficient reference tools that can help non-technical users of developers without the required domain expertise to easily troubleshoot problems in crises. They are well-defined sets of instructions that guide non-technical users through a step-by-step method to address a technical situation, such as debugging a service. They are a crucial knowledge sharing tool, making it important for them to be included in the internal developer portal.
Service catalogs help development teams establish and identify a technical baseline that tells them about the technical capabilities of their systems. Having all of this technical information collated in one place can help the teams gain perspective and reflect on how their systems can be optimized further. In this way, service catalogs serve as solid blueprints that help guide the development of internal developer portals while also making development teams aware of the strengths and weaknesses of the digital systems made available to them.
Allocating service ownership is another important yet often overlooked part of the process of building a comprehensive service catalog. Service ownership is the development philosophy that developers/development teams are fully responsible for the services they work on throughout every stage of the service lifecycle. For instance, let’s say an employee works on a set of microservices that help make the company logo and other branding information on the company website more responsive. They would then assume full-service ownership, i.e., the responsibility of overseeing the writing, testing, launching, and maintenance of all the microservices related to the branding information on the company website. Allocating service ownership helps establish concrete workflows and hierarchies that can be followed when any developer wants to know more about and use a service or troubleshoot a problem related to it. This ultimately helps teams improve their shipping velocity and launch new products faster.
With their various functions, service catalogs are at the core of any internal developer workflow. Putting one in place helps teams set up the foundation upon which the rest of the developer portal can be built.
Setting up data quality scorecards
Organization-wide service catalogs usually hold vast amounts of data collected from several internal sources. All of this data needs to be constantly verified and updated to maintain a basic level of veracity that the catalog should abide by. Without a set process, constant verification of all this data can prove tedious and even unfeasible after a certain point. Data quality scorecards are excellent tools that can help you efficiently work around this problem. Data quality scorecards rank or rate the data connected to each individual service on the basis of completeness and accuracy. Each service is scored based on a few key criteria:
Does the service have a designated owner?
Is the service aptly described in the service catalog?
Is it known what stage of the development process (production, testing, maintenance, or design) the service belongs to?
Having the requisite information on all of these key aspects makes a service catalog more complete, trustworthy, and by extension, more useful for development teams. In addition to this data, the service catalog should also be fed as much supplementary information about the services as possible. This includes information about the specific environments needed to develop and run these services, environment-based dependencies, and other technical requirements, like compliance with data security standards such as Payment Card Industry (PCI) and General Data Protection Regulation (GDPR).
Another important thing to keep in mind while scoring each service is the veracity of the information being entered into the service catalog. It is good practice to get domain specialists or specific service owners to verify all the information related to a service before it is entered or updated on the actual catalog. Further, you should be mindful of the fact that you are expected to score the correctness and completeness of the information related to each service and not the services themselves. Parameters like service quality and service maturity should not in any way influence how services are scored when you set up scorecards in your service catalog.
Service catalogs are not merely static databases but ever-useful information repositories that need to be constantly updated to reflect the latest system changes. Given the size and scale of the architectures that most modern businesses work with, developers need to ensure the overall veracity and completeness of a piece of data being made available to them through a service catalog. Scorecarding saves developers the trouble of physically verifying the system information they refer to and allows teams to highlight and overcome the gaps in their cataloging efforts. Doing so enables teams to refer to the catalog with the confidence that the information in it is accurate and can be used in their development efforts without any hesitation.
Identifying opportunities for using the developer portal
Once your developer portal (and its service catalog) is collated and audited, it is time for you to start identifying and outlining the project opportunities where it could be used. Marking suitable opportunities ahead of time helps development teams avoid the hassle of having to decide whether the portal should be used and if yes, in what capacity, before starting work on each project. It also helps maximize the utility of developer portals by ensuring that they are used to their full potential, whenever possible. Furthermore, the simplest way to drive adoption of an internal developer portal is to identify where your developers are struggling and show them how exactly the portal can support them. If you are struggling to identify opportunities, this is a great starting point.
You can start outlining viable opportunities by going over your list of goals and objectives. If you’re setting up an internal developer portal for the first time, the planning and development processes will likely take up significant time. Depending on the estimated time needed to have the portal up and running, you can start collating a list of all future projects that your company is planning to undertake during the rest of the year. The opportunities for using the developer portal should then be identified and marked (including the scope of use) against each project. For instance, if your team wants to build a Jenkins automation project next year, you will most likely have to test it for build flakiness. This would require you to generate an elaborate report with a detailed service list. Instead of manually collecting and collating all of this data for the report, you can refer to the service catalog for building a reliable service list. Having a certain degree of foresight into future projects is always beneficial to development teams as it helps them list the requirements and workflows well in advance, which ultimately makes the development process quicker and much more efficient.
Internal development portals must evolve as the teams that use them grow and choose to take their software development processes in different directions. As a result, another aspect of having foresight into future projects is identifying the shortfalls in or outdated aspects of your current service catalog and bridging the gaps before the commencement of a new project. For example, say you identify a project that would require your development teams to have ready access to API and runtime-related information about every service. Based on this foresight, you can prompt your team to include said information in the service catalog that they are building for the soon-to-be-launched developer portal.
As your systems grow, as will your portal. The goal here should be to create a viable balance between identifying and creating project opportunities where your internal developer portal can be used to boost productivity and promote development efficiency. Ensuring that the portal is consistently updated with accurate and relevant information is the first step to meeting that goal as often as possible.
Exploring the future potential of your developer portal
Aside from functioning as a reference database for your future projects, internal developer portals can be customized to serve a wide variety of business and development needs. For example, the information within your service catalog can be used to assign service maturity scores to every service and sub-service made available to your developers. This helps teams gauge the overall level of technical proficiency that the company currently operates at and highlight important flaws within the system.
Developer portals can also be used to drive the adoption of the latest security standards that ensure compliance with all relevant data privacy and security laws like the GDPR and the CPRA. This is especially important when teams operate autonomously but still need to all meet the same requirements. Scorecards can be employed within internal developer portals to ensure compliance across the board.
When used correctly, your developer portal can become a holistic productivity enhancement tool that allows you to have greater visibility into your system and drives the adoption of the latest standards and development practices in place today. Developers that see a drop in productivity due to a lack of quick and easy access to the information they need, for instance, stand to benefit a great deal from having an internal developer portal at their disposal.
The task of onboarding new developers, which can otherwise seem cumbersome and riddled with confusion both the newcomers, is also made simpler and more efficient thanks to internal developer portals. With the appropriate permissions in place, the portal can step in the place of a senior developer who is stuck answering basic queries that new developers are bound to have. Keeping in mind that both parties may struggle at this stage (i.e. while learning or teaching the ropes of the team’s workflows and processes), the portal, armed with the right documentation and up-to-date information, can provide the support they need.
Finally, keep in mind that no two internal developer portals are built alike. Start with the tools and processes your teams are currently employing, and build the portal around those. We also highly recommend incorporating new-age visibility tools like veracity scorecards, maturity level indicators, and SLO scores to help customize your developer portals according to your specific business needs and objectives.
How Cortex can help
The widespread adoption of microservice-based application architecture has made it more difficult for development teams to have complete visibility into their digital systems. Critical information about every service resides in specific tools and environments only accessible to specific teams, thereby making it tribal knowledge. Cortex’s cutting-edge SRE and project management solutions help you gain complete visibility into your IT tools and the development teams that work with them. We do this through our service offerings that help teams:
Monitor engineering efficiency.
Automate production readiness.
Monitor service ownership.
Ensure secure cloud migrations.
Get started with our Service Catalog and begin setting up the appropriate Scorecards to keep data quality in check. For more information, book a demo with us.
