update: onboarding improvements (JetBrains#3233)

Author: danil-pavlov

docs/images/multiplatform-mobile/create-first-app/first-multiplatform-project-3.png

@@ -17,15 +17,15 @@ Here you will learn how to create and run your first Kotlin Multiplatform Mobile
 1. In Android Studio, select **File | New | New Project**.
 2. Select **Kotlin Multiplatform App** in the list of project templates, and click **Next**.  
 
-    ![Mobile Multiplatform project template](multiplatform-mobile-project-wizard-1.png)
+    ![Mobile Multiplatform project template](multiplatform-mobile-project-wizard-1.png){width=700}
 
 3. Specify a name for your first application, and click **Next**.  
 
-    ![Mobile Multiplatform project - general settings](multiplatform-mobile-project-wizard-2.png)
+    ![Mobile Multiplatform project - general settings](multiplatform-mobile-project-wizard-2.png){width=700}
 
 4. In the **iOS framework distribution** list, select the **Regular framework** option.
 
-   ![Mobile Multiplatform project - additional settings](multiplatform-mobile-project-wizard-3.png)
+   ![Mobile Multiplatform project - additional settings](multiplatform-mobile-project-wizard-3.png){width=700}
 
    > We recommend using the regular framework for your first project, as this option doesn't require third-party tools and
    > has less installation issues.
@@ -118,18 +118,21 @@ If you want to run your application on a simulated device, you can add a new run
     ![New run configuration for iOS application](ios-new-configuration.png)
 
 3. Name your configuration.
+4. Select the **Xcode project file**. For that, navigate to your project, for example **KotlinMultiplatformSandbox**,
+   open the`iosApp` folder and select the `.xcodeproj` file.
 
-4. Select a simulated device in the **Execution target** list, and then click **OK**.
+5. In the **Execution target** list, select a simulated device and click **OK**.
 
     ![New run configuration with iOS simulator](ios-new-simulator.png)
 
-5. Click **Run** to run your application on the new simulated device.
+6. Click **Run** to run your application on the new simulated device.
 
 #### Run on a real iOS device {initial-collapse-state="collapsed"}
 
-1. [Connect a real iPhone device to Xcode](https://developer.apple.com/documentation/xcode/running_your_app_in_the_simulator_or_on_a_device).
-2. [Create a run configuration](#run-on-a-new-ios-simulated-device) by selecting iPhone in the **Execution target** list.
-3. Click **Run** to run your application on the iPhone device.
+1. Connect a real iPhone device to Xcode.
+2. Make sure to code sign your app. For more information, see the [official Apple documentation](https://developer.apple.com/documentation/xcode/running-your-app-in-simulator-or-on-a-device/).
+3. [Create a run configuration](#run-on-a-new-ios-simulated-device) by selecting iPhone in the **Execution target** list.
+4. Click **Run** to run your application on the iPhone device.
 
 > If your build fails, follow the workaround described in [this issue](https://youtrack.jetbrains.com/issue/KT-40907).
 >
@@ -165,8 +168,10 @@ the Kotlin standard library function for reversing text that works on all platfo
 
 ## Next step
 
-[Learn about dependencies and add a third-party library to your project](multiplatform-mobile-dependencies.md)
-to expand its functionality.
+In the next part of the tutorial, you'll learn about dependencies and add a third-party library to expand
+the functionality of your project.
+
+**[Proceed to the next part](multiplatform-mobile-dependencies.md)**
 
 ### See also
 

docs/images/multiplatform-mobile/create-first-app/first-multiplatform-project-on-android-1.png

@@ -77,7 +77,7 @@ the number of days from today until the new year using the `date-time` date arit
 
         fun greeting(): String {
             return "Guess what it is! > ${platform.name.reversed()}!" +
-            "\nThere are only ${daysUntilNewYear()} days left until New Year! 🎅🏼 "
+            "\nThere are only ${daysUntilNewYear()} days left until New Year! 🎆"
         }
     }
     ```
@@ -88,7 +88,9 @@ the number of days from today until the new year using the `date-time` date arit
 
 ## Next step
 
-[Add more dependencies and more complex logic to your project](multiplatform-mobile-upgrade-app.md).
+In the next part of the tutorial, you'll add more dependencies and more complex logic to your project.
+
+**[Proceed to the next part](multiplatform-mobile-upgrade-app.md)**
 
 ### See also
 

docs/images/multiplatform-mobile/create-first-app/first-multiplatform-project-on-android-2.png

@@ -16,7 +16,7 @@ Kotlin Multiplatform Mobile (KMM) is an SDK designed to simplify the development
 You can share common code between iOS and Android apps and write platform-specific code only where it's necessary.
 Common use cases for Kotlin Multiplatform Mobile include implementing a native UI or working with platform-specific APIs.
 
-> You can also watch this [introductory video](https://www.youtube.com/watch?v=GcqFhoUuNNI) with a general explanation of
+> You can also watch this [introductory video](https://www.youtube.com/watch?v=mdN6P6RI__k) with a general explanation of
 > what Kotlin Multiplatform Mobile is and how to use it in your projects.
 >
 {type="tip"}
@@ -35,7 +35,9 @@ Get to know Kotlin Multiplatform Mobile and create a mobile app that works on bo
 
 ## Next step
 
-Start by [setting up an environment](multiplatform-mobile-setup.md) for Kotlin Multiplatform Mobile development.
+Start by setting up an environment for Kotlin Multiplatform Mobile development.
+
+**[Proceed to the next part](multiplatform-mobile-setup.md)**
 
 ### See also
 

docs/images/multiplatform-mobile/create-first-app/multiplatform-mobile-project-wizard-3.png

@@ -135,7 +135,9 @@ To make sure everything works as expected, install and run the KDoctor tool:
 
 ## Next step
 
-Once the setup is complete, you can start [creating your first cross-platform mobile application](multiplatform-mobile-create-first-app.md).
+In the next part of the tutorial, you'll create your first cross-platform mobile application.
+
+**[Proceed to the next part](multiplatform-mobile-create-first-app.md)**
 
 ## Get help
 

docs/images/multiplatform-mobile/create-first-app/multiplatform-mobile-upgrade.png

@@ -151,6 +151,8 @@ data class RocketLaunch (
     import kotlinx.serialization.json.Json
 
     class Greeting {
+        private val platform: Platform = getPlatform()
+        
         private val httpClient = HttpClient {
             install(ContentNegotiation) {
                 json(Json {
@@ -182,7 +184,7 @@ data class RocketLaunch (
                 httpClient.get("https://api.spacexdata.com/v4/launches").body()
             val lastSuccessLaunch = rockets.last { it.launchSuccess == true }
             return "Guess what it is! > ${platform.name.reversed()}!" +
-                    "\nThere are only ${daysUntilNewYear()} left until New Year! 🎅🏼 " +
+                    "\nThere are only ${daysUntilNewYear()} left until New Year! 🎆" +
                     "\nThe last successful launch was ${lastSuccessLaunch.launchDateUTC} 🚀"
         }
     }
@@ -274,8 +276,12 @@ the shared module, which contains all the business logic.
 The module is already connected to the iOS project — the Android Studio plugin wizard did all the configuration. The module
 is already imported and used in `ContentView.swift` with `import shared`.
 
+> If you see an error saying that the shared module is unresolved, run the app.
+> 
+{type="tip"}
+
 1. Launch your Xcode app and select **Open a project or file**.
-2. Navigate to your project, for example KotlinMultiplatformSandbox, and select the `iosApp` folder. Click **Open**.
+2. Navigate to your project, for example **KotlinMultiplatformSandbox**, and select the `iosApp` folder. Click **Open**.
 3. In `iosApp/iosApp.swift`, update the entry point for your app:
 
    ```swift
@@ -315,8 +321,8 @@ is already imported and used in `ContentView.swift` with `import shared`.
     ```
 
    * `ViewModel` is declared as an extension to `ContentView`, as they are closely connected.
-   * The [Combine framework](https://developer.apple.com/documentation/combine) connects the view model (ContentView.ViewModel)
-   with the view (ContentView).
+   * The [Combine framework](https://developer.apple.com/documentation/combine) connects the view model (`ContentView.ViewModel`)
+   with the view (`ContentView`).
    * `ContentView.ViewModel` is declared as an `ObservableObject`.
    * The `@Published` wrapper is used for the `text` property.
    * The `@ObservedObject` property wrapper is used to subscribe to the view model.
@@ -349,7 +355,7 @@ is already imported and used in `ContentView.swift` with `import shared`.
    * The `greeting()` function was marked with the `@Throws(Exception::class)` annotation. So any exceptions that are
    instances of the `Exception` class or its subclass will be propagated as `NSError`, so you can handle them in the `completionHandler`.
    * When calling Kotlin `suspend` functions from Swift, completion handlers might be called on threads other than main,
-   see the [iOS intergation](native-ios-integration.md#completion-handlers) in the Kotlin/Native memory manager.
+   see the [iOS integration](native-ios-integration.md#completion-handlers) in the Kotlin/Native memory manager.
    That's why `DispatchQueue.main.async` is used to update `text` property.
 
 6. Re-run both **androidApp** and **iosApp** configurations from Android Studio to make sure your app's logic is synced:
@@ -358,7 +364,9 @@ is already imported and used in `ContentView.swift` with `import shared`.
 
 ## Next step
 
-Now it's time to [wrap up your project](multiplatform-mobile-wrap-up.md) and see what's next.
+In the final part of the tutorial, you'll wrap up your project and see what steps to take next.
+
+**[Proceed to the next part](multiplatform-mobile-wrap-up.md)**
 
 ### See also