Adding more docs

Author: Guille Vigil

docs/getting-started/img/idp.png

@@ -6,4 +6,39 @@ sidebar_position: 2
 
 ## What is an Internal Developer Platform?
 
-An Internal Developer Platform (IDP) is a platform that allows developers to create, manage and deploy their applications. It is a set of practices and tools that allow developers to build, test, and deploy their applications in a consistent and reliable way.
+An Internal Developer Platform (IDP) is a platform that allows developers to create, manage and deploy their applications. It is a set of practices and tools that allow developers to build, test, and deploy their applications in a consistent and reliable way. It is a comprehensive toolset that streamlines and automates the software development lifecycle, aiming to boost efficiency, standardize processes, and reduce complexity for developers. By providing a unified framework for development, operations, and security tasks, IDPs enable teams to focus more on coding and less on the overhead associated with deploying and managing applications. Here’s a detailed look into what an IDP is, its key components, benefits, and best practices for implementation.
+
+![With and without IDP](./img/idp.png)
+
+## Definition
+
+An IDP is a self-service platform that abstracts complex cloud environments and operational tasks into a simpler, developer-friendly interface. It integrates various tools and technologies used in software development, deployment, monitoring, and maintenance into a cohesive ecosystem that developers can interact with through a unified dashboard or command-line interface.
+
+## Key Components
+
+1. **Source Control Management (SCM)**: Integrates with SCM systems like Git to automate the flow of code from version control to production.
+2. **Continuous Integration and Continuous Deployment (CI/CD)**: Automates the build, test, and deployment pipelines, ensuring that new code changes are automatically built, tested, and deployed.
+3. **Infrastructure as Code (IaC)**: Manages and provisions cloud resources using code, enabling repeatable and consistent environment setups.
+4. **Monitoring and Logging**: Centralizes logging, monitoring, and alerting tools to provide insights into application performance and troubleshoot issues.
+5. **Security and Compliance**: Embeds security practices into the development lifecycle, from automated code scanning to runtime security policies.
+6. **Collaboration and Documentation**: Facilitates team collaboration and knowledge sharing with integrated documentation tools and communication platforms.
+
+## Benefits
+
+- Increased Developer Productivity: By automating repetitive tasks and standardizing development workflows, developers can focus on writing code rather than managing infrastructure.
+- Enhanced Collaboration: Teams can work more efficiently together with integrated tools for communication, documentation, and version control.
+- Improved Quality and Reliability: Automated testing and deployment processes ensure that code changes are validated and applied consistently, reducing the risk of errors.
+- Faster Time to Market: Streamlined workflows and reduced manual intervention lead to quicker release cycles, allowing organizations to respond faster to market demands.
+- Scalability and Flexibility: IDPs support scalable cloud-native technologies and can adapt to changing business requirements and technology landscapes.
+
+## Best Practices for Implementation
+
+1. Assess Your Needs: Understand the specific challenges and requirements of your development teams to choose the right tools and features for your IDP.
+2. Start Small and Expand Gradually: Begin with a core set of features and gradually add more tools and capabilities based on feedback and evolving needs.
+3. Ensure Scalability and Flexibility: Choose technologies and architectures that can grow with your organization and accommodate new tools and practices.
+4. Foster a Culture of Collaboration: Encourage teams to share knowledge and collaborate closely, leveraging the IDP to bridge gaps between development, operations, and security.
+5. Prioritize Security and Compliance: Embed security practices into the development process and ensure that your IDP supports compliance with relevant regulations and standards.
+
+## Conclusion
+
+An Internal Developer Platform is a powerful enabler for modern software development practices, providing a unified environment for development, deployment, and operations tasks. By automating and streamlining the software development lifecycle, IDPs help organizations achieve faster time to market, improved quality, and increased developer productivity. As organizations continue to adopt cloud-native technologies and modern development practices, IDPs will play a crucial role in driving efficiency, collaboration, and innovation across development teams.

docs/getting-started/img/portal.png

@@ -6,4 +6,40 @@ sidebar_position: 3
 
 ## What is an Internal Developer Portal?
 
-An Internal Developer Portal is a platform that allows developers to create, manage and deploy their applications. It is a set of practices and tools that allow developers to build, test, and deploy their applications in a consistent and reliable way.
+An Internal Developer Portal serves as a centralized hub for an organization's software development resources, tools, and documentation. It is designed to improve the developer experience by providing easy access to everything developers need to efficiently build, deploy, and maintain their applications. Below, we delve into the purpose, key features, benefits, and best practices for setting up and managing an effective Internal Developer Portal.
+
+## Purpose
+
+The primary aim of an Internal Developer Portal is to streamline the software development process within an organization by acting as a single point of access for development resources, including APIs, services, tools, best practices, and guidelines. It facilitates knowledge sharing, promotes standardization, and enhances collaboration across development teams.
+
+## Key Features
+
+1. Comprehensive Documentation: Includes detailed documentation for internal APIs, libraries, and frameworks, along with getting-started guides, tutorials, and API references.
+2. API Catalog: A searchable catalog of all internal and external APIs available to developers, including endpoints, authentication methods, and usage policies.
+3. Tool Access: Provides links or integrations with internal tools for continuous integration and deployment (CI/CD), monitoring, logging, and project management.
+4. Environment Management: Enables developers to provision, manage, and access development, testing, and production environments.
+5. Support and Collaboration Features: Offers forums, chat channels, or ticketing systems for developers to seek help, collaborate on projects, and share knowledge.
+6. Access Control: Implements role-based access control to ensure that developers have appropriate access to resources, based on their roles and projects.
+
+![Internal Developer Portal](./img/portal.png)
+
+## Benefits
+
+- Improved Developer Productivity: By providing easy access to resources and documentation, developers can quickly find what they need, reducing the time spent on searching for information or reinventing the wheel.
+- Enhanced Collaboration: Facilitates better communication and knowledge sharing among developers, helping to break down silos between teams.
+- Standardization and Best Practices: Promotes consistency in development practices and use of technologies across the organization, leading to more maintainable and scalable applications.
+- Faster Onboarding: New developers can get up to speed more quickly by accessing comprehensive guides and resources in one place.
+- Increased Innovation: By reducing administrative overhead and streamlining access to tools and services, developers can focus more on innovation and building new features.
+
+## Best Practices for Implementation
+
+1. User-Centric Design: Design the portal with the end-user in mind. Ensure it is intuitive, easy to navigate, and provides quick access to the most needed resources.
+2. Keep Content Up-to-Date: Regularly update documentation, guides, and resources to reflect the latest changes in tools, APIs, and best practices.
+3. Foster a Collaborative Culture: Encourage contributions from all developers to the portal, whether in the form of documentation, tutorials, or tool recommendations.
+4. Integrate with Existing Workflows: Seamlessly integrate the portal with existing tools and workflows to avoid disrupting the development process.
+5. Gather Feedback and Iterate: Continuously collect feedback from users and make improvements to the portal based on this feedback to ensure it remains relevant and useful.
+
+## Conclusion
+
+An Internal Developer Portal is a vital component in fostering a productive, collaborative, and efficient software development environment. By centralizing access to tools, documentation, and resources, an IDP can significantly enhance the developer experience, streamline development workflows, and promote a culture of knowledge sharing and best practices within the organization. Implementing an Internal Developer Portal with a focus on user needs and continuous improvement will lead to more effective and satisfied development teams.
+

docs/getting-started/internal-developer-platform.md

@@ -12,6 +12,8 @@ Platform Engineering is a discipline that focuses on building and maintaining th
 
 Platform Engineering has its roots in the early days of software development. In the early days, developers had to build and maintain their own infrastructure, which was time-consuming and error-prone. As software development became more complex, the need for a dedicated team to manage infrastructure and tools became apparent. Let's take a look at the history of Platform Engineering.
 
+![History of Platform Engineering](./img/history.png)
+
 ### Pre-Cloud Era (before 2006)
 
 Before cloud computing became mainstream, organizations typically managed their own physical servers. The focus was on system administration, network management, and hardware maintenance. Operations teams were responsible for keeping systems running, while development teams focused on building software. The processes were often siloed, leading to inefficiencies and slower time to market.
@@ -32,8 +34,6 @@ Google's introduction of Site Reliability Engineering (SRE) as a discipline brou
 
 Platform Engineering evolved as organizations recognized the need for a dedicated team to build and maintain internal development platforms. These platforms aim to abstract away the complexities of underlying infrastructure and tooling, enabling development teams to focus on building features and products. Platform Engineering incorporates principles from DevOps and SRE, focusing on creating self-service tools, improving developer experience, and optimizing infrastructure for scalability and reliability.
 
-![History of Platform Engineering](./img/history.png)
-
 Today, Platform Engineering is recognized as a critical function within many organizations, especially those adopting microservices architectures and cloud-native technologies. The role of platform engineers continues to evolve with the advent of new technologies such as Kubernetes, serverless computing, and infrastructure as code (IaC). The focus is on building robust platforms that enable faster innovation, improve efficiency, and maintain high levels of security and compliance.
 
 Platform Engineering is a dynamic field that continues to grow in importance as organizations strive for more efficient, scalable, and reliable software delivery practices. Its history reflects the broader evolution of software development and operations practices in response to technological advancements and changing business needs.

docs/getting-started/internal-developer-portal.md

@@ -2,4 +2,69 @@
 sidebar_position: 4
 ---
 
-# Platform vs Portal
+# Platform vs Portal
+
+The terms "Internal Developer Platform" (IDP) and "Internal Developer Portal" are often used in the context of software development infrastructure, but they serve different, albeit complementary, functions within an organization. Here’s a breakdown of the key differences between a platform and a portal:
+
+## Internal Developer Platform (IDP)
+
+### Purpose
+
+- An IDP is a comprehensive set of tools and technologies that streamline the software development lifecycle (SDLC), from coding and building to deployment and monitoring.
+- It automates and integrates various processes within the SDLC to improve efficiency, standardize development workflows, and facilitate DevOps practices.
+
+### Key Components
+
+- Continuous Integration and Continuous Deployment (CI/CD) pipelines
+- Infrastructure as Code (IaC) for environment provisioning
+- Monitoring, logging, and alerting systems
+- Security and compliance tooling
+- Collaboration and version control integrations
+
+### Benefits
+
+- Increases developer productivity by automating repetitive tasks
+- Enhances collaboration across development, operations, and security teams
+- Improves application quality and deployment reliability
+- Speeds up the time to market for new features and applications
+
+### Usage
+
+Used by developers, operations teams, and security professionals to manage the end-to-end development and deployment process.
+
+## Internal Developer Portal
+
+### Purpose
+
+- An Internal Developer Portal acts as a centralized hub for developers to access information, tools, and resources needed for their work.
+- It primarily focuses on improving the developer experience by making it easier to find and use internal and external APIs, documentation, and development tools.
+
+### Key Components
+
+- Comprehensive documentation for APIs, tools, and best practices
+- API catalogs with detailed information on how to use them
+- Access to development, testing, and production environments
+- Collaboration tools for knowledge sharing and support
+- Integration with SCM (Source Control Management) systems like Git
+
+### Benefits
+
+- Streamlines access to essential development resources and information
+- Facilitates knowledge sharing and collaboration within and across teams
+- Promotes standardization and best practices in software development
+- Accelerates onboarding of new developers
+
+### Usage
+
+Primarily targeted at software developers who need quick and easy access to APIs, tools, documentation, and support.
+
+## Summary of Differences
+
+| Aspect | Internal Developer Platform | Internal Developer Portal |
+| ------ | --------------------------- | ------------------------- |
+| Purpose | Streamline the SDLC and DevOps practices | Improve the developer experience and access to resources |
+| Key Components | CI/CD, IaC, monitoring, security, collaboration | Documentation, API catalogs, environments, collaboration |
+| Benefits | Increased productivity, collaboration, reliability | Streamlined access, knowledge sharing, standardization |
+| Usage | Developers, operations, security teams | Software developers |
+
+In essence, while an Internal Developer Platform is about streamlining and automating the technical aspects of development workflows, an Internal Developer Portal focuses on providing easy access to the resources developers need to do their jobs effectively. Organizations often implement both to maximize productivity, collaboration, and innovation in software development.