Improve typescript integration docs

docs/tutorials/HowToCreateAService.md

@@ -233,7 +233,7 @@ This section is optional when you're mainly using JavaScript or if your service
 If you plan to have your service used by others, providing good TypeScript integration is highly recommended.
 
 Back in the `math` package, we will define the public interface for `"math.MathService"`.
-Pure interface descriptions are conventionally placed into a file called `api.ts`, but they should also be exported from the package's `main` entry point for convenience.
+Pure interface descriptions are conventionally placed into a file called `api.ts`, but they should also be exported from the package's `main` entry point (usually `index.ts`) for convenience.
 
 Because we do not intend to export any classes, functions or constants, we'll just make `api.ts` our `main` for now:
 

docs/tutorials/HowToUseAService.md

@@ -249,6 +249,41 @@ export function AppUI() {
 
 After following these steps, your application's external behavior will be unchanged: the attribute will still be updated.
 
+## TypeScript integration
+
+Packages supporting TypeScript will usually contain snippets such as this to declare types of their interface names:
+
+```ts
+// taken from @open-pioneer/integration
+import "@open-pioneer/runtime";
+declare module "@open-pioneer/runtime" {
+    interface ServiceRegistry {
+        "integration.ApiExtension": ApiExtension;
+        "integration.ExternalEventService": ExternalEventService;
+    }
+}
+```
+
+The snippet associates the interface names (strings on the left) with the appropriate TypeScript types.
+When you write `useService("integration.ExternalEventService")`, the compiler will then know that an `ExternalEventService` will be returned.
+
+Sometimes these declarations will not be picked up automatically by the TypeScript compiler for "external" packages,
+for example if the package is never imported explicitly via TypeScript code.
+
+This will result - for example - in missing types or missing auto-completes when using the `useService` hook (`unknown` instead of the actual service type).
+
+To force TypeScript to read the declarations, you can simply import the package (either locally in your implementation file or in a shared `.d.ts` file):
+
+```ts
+// src/types/pioneer-env.d.ts
+
+// Add a line such as this with the package of your choice
+import "@open-pioneer/integration";
+```
+
+Since the import appears in a `d.ts` file, it has no impact on the runtime behavior of your application.
+It will however be read by the TypeScript compiler who can then check your code against the actual interfaces.
+
 ## Further reading
 
 -   [How to create a service](./HowToCreateAService.md)