Merge pull request #2931 from port-labs/PORTN-3707-align-the-docs-with-port-2-0

sivanel97 · web-flow · commit 93512c742e21 · 2025-10-21T17:33:37.000+03:00
Portn 3707 align the docs with port 2 0
diff --git a/docs/actions-and-automations/actions-and-automations.md b/docs/actions-and-automations/actions-and-automations.md
@@ -5,10 +5,9 @@ import PortTooltip from "/src/components/tooltip/tooltip.jsx"
 One of Port's core offerings is the ability to automate and simplify the processes and routines of your developers.  
 This is done using two powerful tools:
 
-## 1. Self-service actions
+## 1. Actions
 
-Create a wide range of personalized, controlled actions that developers can use to scaffold a service, provision a cloud resource, or any other logic that serves your organization.  
-Self-service actions drive developer productivity by providing a consistent and repeatable way to perform common tasks, all with guardrails like manual approvals or consumption policies to comply with organizational standards.
+Actions are executable pieces of logic that developers or AI agents can run. You can create a wide range of personalized, controlled actions to scaffold a service, provision a cloud resource, or any other logic that serves your organization. Actions drive developer productivity by providing a consistent and repeatable way to perform common tasks, all with guardrails like manual approvals or consumption policies to comply with organizational standards.
 
 :::tip Live demo
 For real-world examples of self-service actions, check out our [live demo](https://showcase.port.io/self-serve).
diff --git a/docs/actions-and-automations/create-self-service-experiences/_category_.json b/docs/actions-and-automations/create-self-service-experiences/_category_.json
@@ -1,4 +1,4 @@
 {
-  "label": "Create self-service actions",
+  "label": "Create actions",
   "position": 1
 }
diff --git a/docs/actions-and-automations/create-self-service-experiences/create-self-service-experiences.md b/docs/actions-and-automations/create-self-service-experiences/create-self-service-experiences.md
@@ -14,7 +14,9 @@ import ExecuteActionLocations from '/docs/actions-and-automations/create-self-se
 </center>
 <br/>
 
-Drive developer productivity by allowing developers to use self-service actions like scaffolding a service or provisioning a cloud resource. Developer self-service drives consistency and repeatability and ensures that their routines are intuitive and clear, all with guardrails like manual approvals or consumption policies to comply with organizational standards.
+Actions are executable pieces of logic that either developers or AI agents can run. They drive developer productivity by enabling them to use actions like scaffolding a service or provisioning a cloud resource.  
+
+Actions drive consistency and repeatability and ensure that routines are intuitive and clear, all with guardrails like manual approvals or consumption policies to comply with organizational standards.
 
 Port's action model is designed to be flexible and can be used to cover a wide range of use-cases:
 
@@ -24,7 +26,7 @@ Port's action model is designed to be flexible and can be used to cover a wide r
 4. **Stateful** - every invoked action affects the software catalog by adding/modifying/deleting one or more entities.
 5. **Secure by design** - does not require keys to sensitive infrastructure by using an event-based model. All actions are audited and can include guardrails like manual approval and TTL.
 
-## 💡 Common self-service actions
+## Common self-service actions
 
 - [**Scaffold** a new service](https://docs.port.io/guides/all/scaffold-a-new-service/).
 - [**Create** a cloud resource](https://docs.port.io/guides/all/create-cloud-resource-using-iac).
@@ -37,7 +39,7 @@ In our [live demo](https://showcase.port.io/self-serve), you can see examples fo
 
 ## How does it work?
 
-1. A user **executes an action** from Port's UI interface.
+1. A user or AI agent **executes an action** from Port's UI interface or through API calls.
 2. A pre-defined **payload** containing any desired metadata about the action and its inputs is **sent** to your infrastructure.
 3. A **job is triggered** and the user gets a **continuous indication** about its progress.
 4. Once the action is running, you can use Port's API to **update Port on its status** and provide information such as **logs and links to the resulting handlers**.
diff --git a/docs/customize-pages-dashboards-and-plugins/_category_.json b/docs/customize-pages-dashboards-and-plugins/_category_.json
@@ -1,5 +1,5 @@
 {
-  "label": "Pages & dashboards",
+  "label": "Interface designer",
   "position": 8,
   "className": "custom-sidebar-item sidebar-menu-pages-and-dashboards"
 }
diff --git a/docs/customize-pages-dashboards-and-plugins/customization.md b/docs/customize-pages-dashboards-and-plugins/customization.md
diff --git a/docs/solutions/engineering-360/_category_.json b/docs/solutions/engineering-360/_category_.json
@@ -1,9 +1,9 @@
 {
-    "label": "Engineering 360",
+    "label": "Engineering intelligence",
     "collapsible": true,
     "collapsed": true,
     "position": 3,
     "customProps": {
-      "description": "Engineering 360"
+      "description": "Engineering intelligence"
     }
   }
diff --git a/docs/solutions/engineering-360/overview.md b/docs/solutions/engineering-360/overview.md
@@ -3,15 +3,15 @@ title: Overview
 sidebar_position: 1
 ---
 
-# Engineering 360
+# Engineering intelligence
 
 ## Why measure engineering effectiveness?
 
 Engineering leadership and platform engineers face a critical question: Where should we focus our DevEx efforts to make the biggest impact? With limited resources and competing priorities, identifying the right areas for improvement can mean the difference between meaningful progress and wasted effort.
 
 ## The journey
 
-Engineering360 is about avoiding the trap of perfectionism when it comes to analysis, and instead optimizing towards immediate measurement, insights and improvement regardless of the maturity of your Development Platform. 
+Engineering intelligence is about avoiding the trap of perfectionism when it comes to analysis, and instead optimizing towards immediate measurement, insights and improvement regardless of the maturity of your Development Platform. 
 In the paragraphs below, we will explore a tried and tested formula for initiating a culture of continuous improvement, in multiple cycles of measurement and improvement.
 
 ### Surveys
@@ -52,6 +52,10 @@ A team using Port was able to correlate service complexity (measured by number o
 Another customer was able to identify Tribes with a materially faster time to 10th PR metrics and chose to follow up with a secondment of engineering managers to those teams to learn.
 :::
 
-Port's flexible data model and managed relations create unique opportunities for measuring sophisticated engineering metrics. Unlike traditional tools that are limited to predefined metrics or siloed data sources, Port can normalize and connect data from across your entire engineering ecosystem. This enables tracking of custom metrics that matter specifically to your organization - whether that's measuring cross-team dependencies, tracking technical debt across multiple repositories, or analyzing the impact of architectural decisions on delivery speed. The managed relations between entities allow for multi-dimensional analysis, helping you understand not just what's happening, but where and why. For example, you could analyze deployment frequency not just by team, but by service type, technology stack, or business domain. This deeper insight helps engineering leaders make more informed decisions about where to focus improvement efforts.
+Port's flexible data model and managed relations create unique opportunities for measuring sophisticated engineering metrics. Unlike traditional tools that are limited to predefined metrics or siloed data sources, Port can normalize and connect data from across your entire engineering ecosystem.  
+
+This enables tracking of custom metrics that matter specifically to your organization - whether that's measuring cross-team dependencies, tracking technical debt across multiple repositories, or analyzing the impact of architectural decisions on delivery speed.  
+
+The managed relations between entities allow for multi-dimensional analysis, helping you understand not just what's happening, but where and why. For example, you could analyze deployment frequency not just by team, but by service type, technology stack, or business domain. This deeper insight helps engineering leaders make more informed decisions about where to focus improvement efforts.
 
 You will learn more about [measuring arbitrary engineering metrics](/solutions/engineering-360/more-engineering-metrics) later in this solution.
diff --git a/docs/solutions/incident-management/_category_.json b/docs/solutions/incident-management/_category_.json
@@ -1,9 +1,9 @@
 {
-    "label": "Incident management",
+    "label": "Self-healing incidents",
     "collapsible": true,
     "collapsed": true,
     "position": 2,
     "customProps": {
-      "description": "Incident Management"
+      "description": "Self-healing incidents"
     }
   }
diff --git a/docs/solutions/incident-management/overview.md b/docs/solutions/incident-management/overview.md
@@ -3,7 +3,7 @@ title: Overview
 sidebar_position: 1
 ---
 
-# Incident management
+# Self-healing incidents
 
 ## Why manage incidents using a developer portal?
 
@@ -12,18 +12,18 @@ Incident management is much more than just selecting a tool for paging and rotat
 Imagine you're going to bed on the first night of your first on-call shift at a new company. Predictably, you receive a phone call from an unknown number an some notoriously unfriendly and robotic sounding voice-to-text programme starts reading you an alert description, one syllable at a time.
 
 Your palms sweat, you open your refurbished macbook pro and start logging into everything all at once:
-- Pagerduty to see and acknowledge the event
-- Slack to start an incident channel and open a bridge for all those investigating
-- Dynatrace to explore the telemetry
-- Statuspage to be ready to notify customers of impact
-- Github to review recent changes
-- ArgoCD to review app sync states
-- AWS to be ready to do further investigation around the infrastructure, or take actions to remediate
-- Notion to start taking notes I'll later use in a post-mortem
+- Pagerduty to see and acknowledge the event.
+- Slack to start an incident channel and open a bridge for all those investigating.
+- Dynatrace to explore the telemetry.
+- Statuspage to be ready to notify customers of impact.
+- Github to review recent changes.
+- ArgoCD to review app sync states.
+- AWS to be ready to do further investigation around the infrastructure, or take actions to remediate.
+- Notion to start taking notes I'll later use in a post-mortem.
 
 Regardless of whether it's your first on-call or hundredth, the story above highlights the fact that our fragmented toolchains and complex application architecture takes lots of time away from incident triage, investigation and remediation, towards manual tasks around communication and investigation of the incident itself.
 
-![Incident Management Solution Architecture](/img/solutions/incident-management/incident_management_solution_architecture.png)
+<img src="/img/solutions/incident-management/incident_management_solution_architecture.png" border='1px' />
 
 ## How can Port help?
 
diff --git a/docs/solutions/resource-self-service/_category_.json b/docs/solutions/resource-self-service/_category_.json
@@ -1,9 +1,9 @@
 {
-    "label": "Resource self-service",
+    "label": "Resource management",
     "collapsible": true,
     "collapsed": true,
     "position": 1,
     "customProps": {
-      "description": "Resource Self-Service"
+      "description": "Resource management"
     }
   }
diff --git a/docs/solutions/resource-self-service/overview.md b/docs/solutions/resource-self-service/overview.md
@@ -3,26 +3,26 @@ title: "Overview"
 sidebar_position: 1
 ---
 
-# Resource self-service
+# Resource management
 
-## Why enable resource self-service using a developer portal?
+## Why enable resource management using a developer portal?
 
-Resource self-service is much more than just giving developers access to cloud consoles and hoping for the best. It's a discipline that requires balancing developer velocity with governance, security, and cost control—where developers need instant access to the resources they need while platform teams maintain standards, compliance, and operational excellence. The challenge is providing this access without creating a ticket-driven bottleneck or sacrificing organizational guardrails.
+Resource management is much more than just giving developers access to cloud consoles and hoping for the best. It's a discipline that requires balancing developer velocity with governance, security, and cost control—where developers need instant access to the resources they need while platform teams maintain standards, compliance, and operational excellence. The challenge is providing this access without creating a ticket-driven bottleneck or sacrificing organizational guardrails.
 
 Imagine you're a developer who just joined a new team and needs to spin up a development environment to work on a critical feature. It's Monday morning, and you need:
-- A new database instance for your microservice
-- An S3 bucket for file storage
-- A Kubernetes namespace configured with the right permissions
-- Secrets properly configured and stored
-- Monitoring and observability set up correctly
-- All of this following your organization's security and compliance standards
+- A new database instance for your microservice.
+- An S3 bucket for file storage.
+- A Kubernetes namespace configured with the right permissions.
+- Secrets properly configured and stored.
+- Monitoring and observability set up correctly.
+- All of this following your organization's security and compliance standards.
 
 Without self-service, you're stuck opening tickets, waiting for approvals, and coordinating with multiple teams:
-- Platform team ticket for the database (2-day SLA)
-- Security team approval for the S3 bucket permissions (1-day SLA)
-- DevOps team request for the Kubernetes namespace (3-day SLA)
-- Another ticket for secrets management setup
-- Manual coordination to ensure everything follows company standards
+- Platform team ticket for the database (2-day SLA).
+- Security team approval for the S3 bucket permissions (1-day SLA).
+- DevOps team request for the Kubernetes namespace (3-day SLA).
+- Another ticket for secrets management setup.
+- Manual coordination to ensure everything follows company standards.
 
 By the time you have everything you need, it's Friday, and you've spent a week on infrastructure instead of building features. Meanwhile, the platform team is drowning in repetitive requests, and inconsistent manual processes have created security gaps and cost overruns.
 
@@ -37,9 +37,9 @@ With Port, you can empower developers to provision and manage resources safely a
 - **Built-in governance and compliance**: RBAC, cost controls, security policies, and audit trails baked into every self-service action, ensuring compliance without sacrificing velocity.
 - **Unified resource visibility**: Track all your cloud resources, their relationships, costs, and lifecycle status in a single pane of glass, making it easy to manage sprawl and optimize usage.
 
-## What you'll learn in this solution
+## What you will learn in this solution
 
-This solution guide covers the essential components of building effective resource self-service:
+This solution guide covers the essential components of building effective resource management:
 
 1. **[Create golden paths](/solutions/resource-self-service/create-golden-paths)**: Learn how to design standardized, opinionated workflows that guide developers toward best practices while eliminating decision fatigue. We'll cover scaffolding new services, cloud resource provisioning patterns (RESTful vs GitOps), and secure secrets management.
 
diff --git a/src/components/ProductPillars/ProductPillars.tsx b/src/components/ProductPillars/ProductPillars.tsx
@@ -29,46 +29,46 @@ const Pillar: React.FC<PillarProps> = ({ title, description, demoUrl, demoLabel
 const ProductPillars: React.FC = () => {
   const pillars = [
     {
-      title: 'Software Catalog',
-      description: 'Make Port your own by defining a data model that fits your organization, then use your software catalog as a single source of truth for your software development assets.',
+      title: 'Software catalog',
+      description: 'Build a unified SDLC view by modeling data from across your ecosystem. Define a data model that fits your organization to reduce cognitive load and maintain a single, consistent source of truth.',
       demoUrl: 'https://showcase.port.io/service_catalog',
       icon: 'lists',
     },
     {
-      title: 'Self-Service',
-      description: 'Drive developer productivity and reduce drift by providing developers with pre-configured self-service actions like scaffolding a service or provisioning a cloud resource.',
+      title: 'Actions',
+      description: 'Drive developer productivity and reduce drift by standardizing operations and eliminating knowledge gaps through pre-configured actions like scaffolding a service or provisioning a cloud resource.',
       demoUrl: 'https://showcase.port.io/self-serve',
       icon: 'bolt',
     },
     {
-      title: 'Workflow Automation',
-      description: 'Set up automations to automatically respond to events in your software catalog such as TTL=0 or service degradation, and peform actions like sending a notification or reporting an issue.',
+      title: 'AI agents',
+      description: 'Build your own agents to reduce manual engineering work. Define their goals, access and tools to boost performance and stay in control.',
+      demoUrl: 'https://showcase.port.io/organization/home',
+      icon: 'stars_2',
+    },
+    {
+      title: 'Workflow orchestrator',
+      description: 'Build any flow using automation. Automatically respond to events in your software catalog such as TTL=0 or service degradation. Infuse AI into any workflow to accelerate delivery and eliminate manual effort.',
       demoUrl: 'https://showcase.port.io/settings/automations',
       icon: 'play_circle',
     },
     {
       title: 'Scorecards',
-      description: 'Define and track standards and KPIs for your resources to measure quality, production readiness, productivity, or any other metric you need.',
+      description: 'Define software standards and know they are met. Ensure quality, security, compliance, and velocity for all software catalog components.',
       demoUrl: 'https://showcase.port.io/serviceEntity?identifier=authentication&activeTab=1',
       icon: 'military_tech',
     },
     {
-      title: 'R&D Insights & Reports',
-      description: 'Shine a light on all things engineering, from standards compliance to DORA metrics & AppSec. Make informed decisions based on trends and usage patterns to improve development, optimize performance, and reduce cost.',
-      demoUrl: 'https://showcase.port.io/dora_metrics',
-      icon: 'insights',
-    },
-    {
-      title: 'Dashboards & visualizations',
-      description: 'Create custom dashboards and widgets to track and visualize data about your assets. View trends and gain insights into your development activities, performance, and progress.',
+      title: 'Interface designer',
+      description: 'Build custom interfaces to track asset data, visualize trends, and analyze development performance. Customize each stakeholder’s experience to match their daily work.',
       demoUrl: 'https://showcase.port.io/engineering_overview',
-      icon: 'dashboard',
+      icon: 'design_services',
     },
     {
-      title: 'Role-based access control',
-      description: 'Control access to different parts of your portal based on user roles and permissions. Ensure that only authorized users have access to the information they need to do their jobs.',
+      title: 'Access controls',
+      description: 'Define granular access control for everything in Port. Ensure that only authorized users have access to the information they need to do their jobs.',
       demoUrl: 'https://showcase.port.io/settings/users',
-      icon: 'shield_person',
+      icon: 'manage_accounts',
     }
   ];
 
diff --git a/src/components/guides-section/consts.js b/src/components/guides-section/consts.js
@@ -2,7 +2,7 @@ import guideMetadata from './guide-metadata.json';
 
 export const tagsCategoryMap = {
     "Use-cases": ["SDLC", "K8s for devs", "Incident management", "IaC for devs", "Cloud access management", "Feature flag management", "Security", /*"Cloud cost",*/ "Dev environments", "Engineering metrics", "Dependency management", "API catalog", "Approval workflow"],
-    "Port pillars": ["Actions", "AI", "Automations", "Dashboards", "Scorecards", "RBAC"],
+    "Port pillars": ["Actions", "AI", "Automations", "Dashboards", "Scorecards", "Access controls"],
     Technologies: [
         "GitHub",
         "Github Copilot",
diff --git a/src/css/custom.css b/src/css/custom.css
@@ -392,10 +392,6 @@ html[data-theme="dark"] details details  {
   content: url('/static/img/sidebar-icons/main-menu/resources.svg');
 }
 
-.sidebar-menu-customization .menu__link::before {
-  content: url('/static/img/sidebar-icons/main-menu/customization.svg');
-}
-
 .sidebar-menu-docs-ai-assistant .menu__link::before {
   content: url('/static/img/sidebar-icons/main-menu/docs-ai-assistant.svg');
 }
diff --git a/static/img/guides/icons/Accesscontrols.svg b/static/img/guides/icons/Accesscontrols.svg

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`	`1`	`{`
`2`		`- "label": "Create self-service actions",`
	`2`	`+ "label": "Create actions",`
`3`	`3`	`"position": 1`
`4`	`4`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "label": "Pages & dashboards",`
	`2`	`+ "label": "Interface designer",`
`3`	`3`	`"position": 8,`
`4`	`4`	`"className": "custom-sidebar-item sidebar-menu-pages-and-dashboards"`
`5`	`5`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,9 +1,9 @@`
`1`	`1`	`{`
`2`		`- "label": "Engineering 360",`
	`2`	`+ "label": "Engineering intelligence",`
`3`	`3`	`"collapsible": true,`
`4`	`4`	`"collapsed": true,`
`5`	`5`	`"position": 3,`
`6`	`6`	`"customProps": {`
`7`		`- "description": "Engineering 360"`
	`7`	`+ "description": "Engineering intelligence"`
`8`	`8`	`}`
`9`	`9`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,9 +1,9 @@`
`1`	`1`	`{`
`2`		`- "label": "Incident management",`
	`2`	`+ "label": "Self-healing incidents",`
`3`	`3`	`"collapsible": true,`
`4`	`4`	`"collapsed": true,`
`5`	`5`	`"position": 2,`
`6`	`6`	`"customProps": {`
`7`		`- "description": "Incident Management"`
	`7`	`+ "description": "Self-healing incidents"`
`8`	`8`	`}`
`9`	`9`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,9 +1,9 @@`
`1`	`1`	`{`
`2`		`- "label": "Resource self-service",`
	`2`	`+ "label": "Resource management",`
`3`	`3`	`"collapsible": true,`
`4`	`4`	`"collapsed": true,`
`5`	`5`	`"position": 1,`
`6`	`6`	`"customProps": {`
`7`		`- "description": "Resource Self-Service"`
	`7`	`+ "description": "Resource management"`
`8`	`8`	`}`
`9`	`9`	`}`