7 Most Common Pitfalls When Choosing the Right Internal Developer Platform

Selecting the right Internal Developer Platform (IDP) is a critical decision that shapes the effectiveness of your software development team. An IDP empowers developers with the tools and environments necessary for efficient coding, testing, and deployment, resulting in a streamlined development workflow. However, a poor choice can lead to substantial setbacks, reducing productivity and overall business efficiency. In this article, we will discuss the most common mistakes to avoid when selecting an IDP. We will go through a practical use case for each mistake, followed by best practices to avoid this mistake in the first place.

Morgan Perry

Morgan Perry

November 13, 2023 · 9 min read
7 Most Common Pitfalls When Choosing the Right Internal Developer Platform - Qovery

#Pitfall 1: Neglecting Scalability

#Why scalability matters?

An IDP is sort of a living entity that grows as the organization grows. It is not just about handling more code. It is about making the whole platform, including the integrations, highly scalable. A platform that is not able to scale properly will result in a slow development pace and reduced developer productivity. Opting for an IDP with minimal features might seem appealing initially, but it becomes more of a problem than a solution if it cannot meet future scalability needs.

#Use case

Take the example of a fintech startup with a non-scalable IDP. It could miss critical regulatory deadlines for launching new features, affecting its compliance posture and market competitiveness. This is because the IDP was not built, keeping scalability in mind. 

#How to avoid this pitfall?

  • Future-proofing: Select an IDP that can accommodate future growth in terms of users and data.
  • Modular design: Choose a platform with a modular structure for easier scaling.
  • Performance evaluation: Ensure the IDP meets industry-specific scalability benchmarks.
  • Scalability features: Prioritize IDPs with cloud-based architectures and auto-scaling capabilities.
  • Vendor track record: Select a vendor known for scalable solutions.
  • Flexible integrations: Ensure the IDP supports easy integration with modern tools.
  • Ongoing support: Choose a vendor offering regular updates and robust support.

#Pitfall 2: Overlooking Integration Capabilities

#Why integration capabilities matter?

The IDP should be able to integrate seamlessly with existing tools and infrastructure. That can be different communication tools like Slack, MS Teams, and others. It can be CI/CD tools like Jenkins or Codeship. Cloud vendors like AWS and Azure are also on this list. The IDP should be able to integrate with these tools to have uninterrupted workflows and efficient software development cycles. Let’s grasp this concept through a practical use case. 

#Use case

Take the example of a software development team using a combination of Jenkins for continuous integration, JIRA for project management, and Kubernetes for container orchestration. If the chosen IDP does not offer integrations with these services, the result could be a fragmented development process. Developers might waste time manually bridging the gaps between systems, leading to slower release cycles and increased potential for errors.

#How to avoid this pitfall?

  • Conduct an assessment of your current toolset: Before selecting an IDP, evaluate your current toolset (like Jenkins, JIRA, Kubernetes, Slack, etc.) to understand your integration requirements.
  • Prefer customizable solutions: Prefer the IDPs offering customizable integration options to ensure compatibility with a wide range of tools and services.
  • API flexibility: Choose IDPs with flexible APIs that can easily connect with existing tools and infrastructure.
  • Pre-built integrations: Look for IDPs with pre-built integrations for common tools and platforms like AWS, Azure, Jenkins, Slack, MS Teams, etc. 
  • Involve developers: Include feedback from the software development teams because they are the end users and understand the practical integration needs better.
  • Test integration capabilities: Conduct pilot tests with your critical tools to confirm smooth integration before finalizing the IDP selection, maybe through a demo version or a sandbox. 

#Pitfall 3: Sacrificing Security for Convenience

#Why a secured IDP is so important?

The security of a platform is an inevitable factor for businesses. You may compromise on the look and feel of an IDP temporarily but not on its security. This is because these platforms have sensitive data and critical access points and require robust security measures. The idea that convenience in development can overshadow security is a certain recipe for disaster. Imagine a scenario where a minor lapse in security protocols leads to a significant data breach, disrupting operations and degrading user trust. This is why prioritizing security in IDPs is absolutely essential.

#Use Case

Consider the case of a cloud solutions provider company whose IDP faced a severe breach due to inadequate authentication measures (lack of MFA). The breach allowed unauthorized access to their codebase, leading to the theft of intellectual property and a substantial financial loss.

#How to avoid this pitfall?

  • Enforce Multi-Factor Authentication (MFA): Mandate MFA for all users to significantly reduce the risk of unauthorized access.
  • Regular Security Assessments: Schedule frequent security audits to identify and address vulnerabilities promptly.
  • Robust Encryption Standards: Ensure all sensitive data, both at rest and in transit, is encrypted using industry-standard protocols.
  • Continuous Education and Training: Conduct regular training sessions for developers on the latest security threats and best practices.
  • Stringent Access Controls: Implement the principle of least privilege in access control, ensuring that users have only the necessary permissions required for their role.
  • Stay Updated with Patches: Regularly update the IDP with the latest security patches to protect against new vulnerabilities.

#Pitfall 4: Neglecting Developer Experience & Team Adoption

#Why an easy-to-use IDP matter?

The success of IDPS lies not just in its technical capabilities but in its ease of use. An intuitive self-guiding interface with a smooth developer experience is critical. A platform that challenges rather than facilitates can become a bottleneck, taking away the very efficiency it's meant to bring. When developers struggle to use the UI of an IDP, their productivity drops. The result? Project timelines overrun, morale dips and the adoption of the platform itself becomes a challenging task.

#Use case

Consider a scenario of a software company that introduced a powerful IDP, loaded with features. However, it was not designed with user experience in mind. The interface was clunky, and essential functions were buried under layers of menus. As a result, the talented development team found themselves wrestling more with the platform than delivering the features.

#How to avoid this pitfall?

  • Prioritize user-centric design: Ensure the IDP interface is intuitive and user-friendly. Simplify navigation and make common tasks easily accessible.
  • Involve developers in the selection process: Who better to judge the platform than those who will use it daily? 
  • Offer comprehensive training: Don’t just deploy and disappear. Provide thorough training to help developers get acquainted with the new system.
  • Encourage regular feedback: Keep communication channels open. Regular feedback sessions can help identify pain points early on.
  • Iterate based on usage data: Monitor how the platform is being used. Usage patterns can offer valuable insights for making user-centric improvements.

#Pitfall 5: Ignoring Cost Implications

#Why should you not ignore the cost of IDP?

Understanding the full spectrum of costs associated with an IDP, including the total cost of ownership (TCO), is crucial for several reasons. First, it prevents budgetary surprises that can disrupt the project. Second, a comprehensive cost analysis helps in comparing different platforms more accurately, ensuring that the decision is based on long-term value rather than upfront costs alone. Last but not least, it ensures that the organization is prepared for ongoing expenses, contributing to better financial planning and resource allocation.

#Use case

Consider a scenario where a company opted for an IDP based solely on its low initial setup cost. Midway through implementation, they discovered additional expenses for integration, training, and maintenance, which were not initially budgeted for. This oversight led to a significant budget overrun, forcing the company to reallocate funds from other critical projects, ultimately delaying the IDP deployment and impacting overall business operations.

#How to avoid this pitfall?

  • Conduct comprehensive cost analysis: Before making a decision, calculate the total cost of ownership, which includes setup costs, maintenance, upgrades, training, and support.
  • Anticipate hidden costs: Be vigilant about potential hidden costs such as integration with existing systems, data migration, and any custom development required.
  • Regularly review and update budget estimates: As the project progresses, regularly review and adjust the budget to account for any unforeseen expenses.
  • Seek expert consultation: Engage with financial analysts or consultants who specialize in technology implementations to get an accurate estimate of costs.
  • Include a contingency budget: Always include a contingency fund in the budget to cover unexpected costs without disrupting the project or other organizational finances.

#Pitfall 6: Failing to Match Use Case Requirements

#Why must an IDP match your requirements?

Choosing an IDP without considering your specific use case needs will result in a loss of money and time. The unique demands of your development environment dictate the type of IDP you require. An IDP not suited to your business needs can lead to significant disruptions in workflow, reduced efficiency, and increased frustration among your development team. Let’s see some use cases to understand this pitfall in detail. 

#Use case

Consider a tech startup focusing on rapid mobile app development. They adopted a popular IDP known for its robust data processing capabilities. However, this IDP was overkill for their needs and lacked features for streamlined mobile app development. Eventually, developers spent more time configuring the platform than actually developing the mobile apps. This mistake not only slowed down their development process but also led to budget overruns and team dissatisfaction.

#How to avoid this pitfall?

  • Evaluate your development needs: Conduct a thorough assessment of your development team's requirements before you go for an IDP. Consider factors like project size, compliance needs, and the specific technologies your team uses.
  • Research and compare: Research and shortlist those IDPs that cater to organizations similar to yours in size, industry, and technological needs.
  • Request demos and trials: Once you have shortlisted potential IDPs, request demos or trial periods. This hands-on approach allows your development team to test the platform's compatibility with your use case requirements.

#Pitfall 7: Neglecting Support and Documentation

#Why documentation and support are important?

The ecosystem of support and documentation of an IDP is a factor that cannot be ignored. Comprehensive documentation acts as a roadmap to guide developers through the complexities of the platform. Similarly, strong support ensures that any challenges encountered are immediately addressed. Neglecting these aspects can lead to operational challenges. Without clear guidance, developers may find themselves lost in the platform's functionalities and struggle with troubleshooting and operational inefficiencies. This leads not only to inefficient use of resources and a steep learning curve but can also decelerate the adoption of the platform. Let’s understand this a bit more through a real-life example. 

#Use case

Consider the case of a mid-sized tech company that rolled out a new IDP compromising on documentation or support. The platform was technically advanced but lacked clear, user-friendly documentation. Developers spent excessive time deciphering basic operations, significantly slowing down project timelines. When they encountered issues, the support system could not respond on time, resulting in prolonged downtimes. The result was a noticeable reduction in productivity and frustration among the development team. 

#How to avoid this pitfall?

  • Do not underestimate documentation: Ensure that the documentation is detailed, easy to understand, and regularly updated to reflect the latest features.
  • Establish responsive support channels: Set up a reliable support system, including help desks, FAQs, and user guides, ensuring that help is always at hand when developers need it.
  • Establish a developer community: Encourage the growth of an active developer community around the IDP. This could involve forums, knowledge-sharing webinars, and community-driven projects.


In the article, several key issues are highlighted that organizations should be aware of when selecting an IDP.

  1. Scalability: Ensure the IDP can grow with your company. Failure to do so can slow development and reduce productivity.
  2. Integration Capabilities: The IDP must integrate well with existing tools to maintain efficient workflows.
  3. Security: Prioritizing security is crucial, as vulnerabilities can lead to data breaches and loss.
  4. Developer Experience & Team Adoption: A user-friendly IDP increases developer productivity and eases the adoption process.
  5. Cost Implications: Understand the total cost of ownership to avoid budget overruns.
  6. Matching Use Case Requirements: Select an IDP that fits your specific needs to avoid inefficiencies.
  7. Support and Documentation: Adequate support and clear documentation are essential for efficient platform use and problem-solving.

To make a correct decision, organizations are encouraged to thoroughly evaluate their needs and choose an IDP that aligns with their business and technical requirements. For successful implementation and to maximize value, involve developers in the decision-making process, and don't underestimate the importance of support and documentation.

Your Favorite Internal Developer Platform

Qovery is an Internal Developer Platform Helping 50.000+ Developers and Platform Engineers To Ship Faster.

Try it out now!
Your Favorite Internal Developer Platform
Qovery white logo

Your Favorite Internal Developer Platform

Qovery is an Internal Developer Platform Helping 50.000+ Developers and Platform Engineers To Ship Faster.

Try it out now!
Internal Developer PlatformPlatform EngineeringDevOps