Updated documentation

Author: FlorianRappl

api/configuration/services.md

@@ -21,6 +21,8 @@ interface ConverterService {
 }
 ```
 
+For an explanation of the `ComponentLifecycle` see [Generic component Lifecycle](../lifecycle/index.md).
+
 ```ts
 interface ContainerService {
   createContainer(details: any): Promise<ComponentGetter>;

api/index.md

@@ -1,3 +1,9 @@
 # API
 
-...
+The following documents explain the API structure of Picard.js. In general we distinguish between:
+
+- The actual component API - what you need to know for actually crafting experiences relying on Picard.js
+- The configuration and setup API - what you need to know to customize and build your orchestration behavior on Picard.js
+- The internal APIs - what you need to know for betting extending and understanding Picard.js
+
+We'll start with the [component API](./components/index.md).

data/diagrams.drawio

@@ -2,6 +2,8 @@
 
 The `pi-component` can be used to render a component from a micro frontend on a website.
 
+![`pi-component`](../../images/pi-component.svg)
+
 Consider the following HTML:
 
 ```html

guide/components/pi-component.md

@@ -4,6 +4,8 @@ The `pi-part` component is available exclusively on the server. On the client, t
 
 This component is essentially a replacement rule that is applied by the `decorate` function of Picard.
 
+![`pi-part`](../../images/pi-part.svg)
+
 Consider the following HTML:
 
 ```html

guide/components/pi-part.md

@@ -2,6 +2,8 @@
 
 The `pi-slot` component introduces a micro frontend independent rendering slot. It will automatically look into all currently loaded micro frontends - trying to locate exposed components by the given `name` attribute. All found components will be rendered inside the `pi-slot`.
 
+![`pi-slot`](../../images/pi-slot.svg)
+
 Consider the following HTML:
 
 ```html

guide/components/pi-slot.md

@@ -4,6 +4,8 @@ Picard.js is your comprehensive solution for orchestrating micro frontends, prov
 
 ## Multi Platform
 
+![Multi Platform](../images/multi-platform.svg)
+
 Picard.js is designed to be versatile and adaptable across various environments. Whether you're working in a browser, Node.js, Deno, or Electron, Picard.js seamlessly orchestrates micro frontends, ensuring consistent performance and compatibility.
 
 ## Multi Format
@@ -12,6 +14,8 @@ With Picard.js, you can integrate and manage multiple micro frontend formats eff
 
 ## Multi Framework
 
+![Multi Framework](../images/multi-framework.svg)
+
 Picard.js excels at integrating various frameworks, including single-spa, HTML fragments, and web components. This multi-framework support allows you to choose the best tools for each part of your application, fostering innovation and efficiency.
 
 ## Error Handling
@@ -32,4 +36,6 @@ Debugging with Picard.js is straightforward and integrates seamlessly into your
 
 ## Islands Architecture
 
+![Islands Architecture](../images/islands-architecture.svg)
+
 Picard.js facilitates the creation of island architectures, enabling server-side rendered (SSR) applications that can hydrate and continue on the client side. This approach optimizes performance and user experience, combining the best of SSR and client-side rendering.

guide/features.md

@@ -8,22 +8,34 @@ Today, a rich collection of libraries, tools, and frameworks for creating micro
 
 ### Interoperability
 
+![Interoperability Restrictions](../images/interoperability.svg)
+
 One of the reasons why Picard.js might be interesting for you is that it allows to easily bring in micro frontends. So, instead of requiring to set up some bundler or go into specifics, all you need to do is grab a script and add a web component. That's it!
 
 For owners of existing micro frontend solutions the integration of other micro frontends will no longer break due to technology incompatibilities. If two micro frontends have been written - one using Module Federation and another one using Native Federation - you will no longer require some frankenstein solution, but instead can just embed both; and it will just work.
 
+👉 Want to see this in action? [Example online](https://github.com/picardjs/picard/blob/main/examples/10-dependencies-sharing/index.html)
+
 ### Error Handling
 
+![Error Handling Problems](../images/error-handling.svg)
+
 Error handling has been one of the largest problems in solutions like Module Federation or Native Federation. The low-level nature of these building blocks ensured that you'd need to build something from the beginning. Unfortunately, this meant that you are rather creating and maintaining a micro frontend framework than actually solving a business problem.
 
 With Picard.js error handling is integrated from the ground up. You reference an invalid component? Nothing bad will happen. The component crashes or does not accept the given inputs? The solution will just continue - if you care you can pick up the error and display something else instead.
 
+👉 Want to see this in action? [Example online](https://github.com/picardjs/picard/blob/main/examples/06-static-page-single-spa/mfs/red/src/Product.jsx#L87)
+
 ### Technology Agnostic
 
+![Technology Enforcement](../images/tech-agnostic.svg)
+
 A design goal of Picard.js was to work without any tooling. As such owners of existing projects (let's say an existing page created with PHP or some other SSR technology such as ASP.NET) don't need to integrate additional tooling. They just add some additional markup to their generated HTML response and everything works.
 
 One advantage of this approach is that - out-of-the-box - Picard.js is technology agnostic. While other approaches require specific tooling to work we don't need this here. As a result, Picard.js can also be used with tooling that is rather micro frontend hostile such as the Angular CLI. As long as there is some HTML somewhere you can add the script and use the web components.
 
+👉 Want to see this in action? [Example online](https://github.com/picardjs/picard/blob/main/examples/01-static-page/index.html)
+
 ## Why use a Library as Orchestrator?
 
 Because a library is lightweight and does not stand in your way. Of course, you can use a full framework or invent your own thing (and in some scenarios that might be the right thing to do), but usually the orchestration itself should be *just* done. No questions asked.