diff --git a/docs/topics/multiplatform/native-cocoapods-xcode.md b/docs/topics/multiplatform/native-cocoapods-xcode.md
index 9e9e5643aaa..9757f110a00 100644
--- a/docs/topics/multiplatform/native-cocoapods-xcode.md
+++ b/docs/topics/multiplatform/native-cocoapods-xcode.md
@@ -59,7 +59,12 @@ dependency by calling `pod install` manually for each Xcode project. In other ca
     end
     ```
 
-6. Run **Reload All Gradle Projects** in IntelliJ IDEA (or **Sync Project with Gradle Files** in Android Studio)
+6. Run `pod install` in you project directory.
+
+   When you run `pod install` for the first time, it creates the `.xcworkspace` file. This file
+   includes your original `.xcodeproj` and the CocoaPods project.
+7. Close your `.xcodeproj` and open the new `.xcworkspace` file instead. This way you avoid issues with project dependencies.
+8. Run **Reload All Gradle Projects** in IntelliJ IDEA (or **Sync Project with Gradle Files** in Android Studio)
    to re-import the project.
 
 ## Xcode project with several targets
@@ -109,7 +114,12 @@ dependency by calling `pod install` manually for each Xcode project. In other ca
     end
     ```
 
-6. Run **Reload All Gradle Projects** in IntelliJ IDEA (or **Sync Project with Gradle Files** in Android Studio)
+6. Run `pod install` in you project directory.
+
+   When you run `pod install` for the first time, it creates the `.xcworkspace` file. This file
+   includes your original `.xcodeproj` and the CocoaPods project.
+7. Close your `.xcodeproj` and open the new `.xcworkspace` file instead. This way you avoid issues with project dependencies.
+8. Run **Reload All Gradle Projects** in IntelliJ IDEA (or **Sync Project with Gradle Files** in Android Studio)
    to re-import the project.
 
 You can find a sample project [here](https://github.com/Kotlin/kmm-with-cocoapods-multitarget-xcode-sample).
@@ -117,4 +127,4 @@ You can find a sample project [here](https://github.com/Kotlin/kmm-with-cocoapod
 ## What's next
 
 See [Connect the framework to your iOS project](https://www.jetbrains.com/help/kotlin-multiplatform-dev/multiplatform-integrate-in-existing-app.html#connect-the-framework-to-your-ios-project)
-to learn how to add a custom build script to build phases in Xcode projects.
\ No newline at end of file
+to learn how to add a custom build script to build phases in Xcode projects.
diff --git a/docs/topics/multiplatform/native-cocoapods.md b/docs/topics/multiplatform/native-cocoapods.md
index aad8a2cca4d..faa127dd0af 100644
--- a/docs/topics/multiplatform/native-cocoapods.md
+++ b/docs/topics/multiplatform/native-cocoapods.md
@@ -216,40 +216,45 @@ the build process of an Xcode project.
 
 ## Update Podfile for Xcode
 
-If you want to import your Kotlin project in an Xcode project, you need to make some changes to your Podfile:
+If you want to import your Kotlin project to an Xcode project:
 
-* If your project has any Git, HTTP, or custom Podspec repository dependencies, you should also specify the path to
-the Podspec in the Podfile.
+1. Make changes in your Podfile:
 
-    For example, if you add a dependency on `podspecWithFilesExample`, declare the path to the Podspec in the Podfile:
+   * If your project has any Git, HTTP, or custom Podspec repository dependencies, you should specify the path to
+     the Podspec in the Podfile.
 
-    ```ruby
-    target 'ios-app' do
+     For example, if you add a dependency on `podspecWithFilesExample`, declare the path to the Podspec in the Podfile:
+
+     ```ruby
+     target 'ios-app' do
         # ... other dependencies ...
-        pod 'podspecWithFilesExample', :path => 'cocoapods/externalSources/url/podspecWithFilesExample'
-    end
-    ```
+        pod 'podspecWithFilesExample', :path => 'cocoapods/externalSources/url/podspecWithFilesExample' 
+     end
+     ```
 
-    The `:path` should contain the filepath to the Pod.
+     The `:path` should contain the filepath to the Pod.
 
-* When you add a library from the custom Podspec repository, you should also specify the [location](https://guides.cocoapods.org/syntax/podfile.html#source)
-of specs at the beginning of your Podfile:
+   * When you add a library from the custom Podspec repository, you should also specify the [location](https://guides.cocoapods.org/syntax/podfile.html#source)
+     of specs at the beginning of your Podfile:
 
-    ```ruby
-    source 'https://github.com/Kotlin/kotlin-cocoapods-spec.git'
+     ```ruby
+     source 'https://github.com/Kotlin/kotlin-cocoapods-spec.git'
 
-    target 'kotlin-cocoapods-xcproj' do
-        # ... other dependencies ...
-        pod 'example'
-    end
-    ```
+     target 'kotlin-cocoapods-xcproj' do
+         # ... other dependencies ...
+         pod 'example'
+     end
+     ```
 
-> After making changes in the Podfile, run **Reload All Gradle Projects** in IntelliJ IDEA
-> (or **Sync Project with Gradle Files** in Android Studio) to re-import the project.
->
-{style="note"}
+2. Run `pod install` in you project directory.
+
+   When you run `pod install` for the first time, it creates the `.xcworkspace` file. This file
+   includes your original `.xcodeproj` and the CocoaPods project.
+3. Close your `.xcodeproj` and open the new `.xcworkspace` file instead. This way you avoid issues with project dependencies.
+4. Run **Reload All Gradle Projects** in IntelliJ IDEA (or **Sync Project with Gradle Files** in Android Studio)
+   to re-import the project.
 
-If you don't make these changes to the Podfile, the `podInstall` task will fail, and the CocoaPods plugin will show
+If you don't make these changes in the Podfile, the `podInstall` task will fail, and the CocoaPods plugin will show
 an error message in the log.
 
 ## Possible issues and solutions