update Readme

SICKAG · Oct 27, 2022 · fdae101 · fdae101
1 parent 42a17b9
commit fdae101
Show file tree

Hide file tree

Showing 2 changed files with 54 additions and 50 deletions.
diff --git a/README.md b/README.md
@@ -1,52 +1,58 @@
 # Collage
 
-
 ## Introduction
 
-- `Collage` is a library for creating and embedding micro frontends as `fragments`.
-- A `fragment` is a micro frontend that is described with the `Collage` library.
-- An `arrangement` is a composition of one or more `fragments`.
-- A `fragment` can be an `arrangement` itself.
-- A `fragment` should always be self contained
-
-For further documentation, please see [features](/docs/docs/features.md), [concepts](/docs/docs/concepts.md) and [api](/docs/docs/core-api.md), as well as the [getting-started](/docs/guide/getting-started.md)
-
-
-> **Caution!**
-> 
-> Since you do not know how a possible Arrangement might fill the config values you 
-> expect, and since they might set those values on the DOM, meaning all values 
-> would be of type string, you cannot assume any specific type for your config
-> values.
->
-> Be prepared, to use `Number(config.key)` or Template strings or other sensible
-> type mappings for your needs.
-
-## Current State
-
-* [x] create custom element
-* [x] add 'name' attribute to custom element
-* [ ] add 'disconnected' attribute to custom element
-* [x] translate initialisation for simple services
-* [x] translate initialisation for complex services
-* [ ] add named Fragments in initialisation (init with function)
-* [x] translate usage of simple services
-* [x] translate usage of complex services
-* [x] add direct function calls on named Fragments
-* [x] translate api for topic initialisation
-* [x] translate api for topic usage
-* [ ] create unsubscribe in API v1
-
-## Discussion and open points
-
-* **[Topic-message-origin]** Do we need/want a generic (core) way to communicate
-  the origin of a message that has been published onto a topic?
-  This would simplify usecases like navigation and may be of broader use.
-
-## Known Bugs
-
-* **[TopicBug]** Some strange behaviour with topics needs to be resolved, where
-  a topic subscriber would always get 'subscribed [topic]' as first message and
-  would later on not be able to receive a new message with exactly that wording
-
-
+`Collage` is a library for creating and embedding micro frontends as `fragments`.
+
+With Collage you can upgrade a web application of all sorts to either a micro frontend or an application capable of embedding micro frontends - basically both at the same time. Doing so, Collage works on the scope of HTML Documents by enhancing a Document with certain capabilities, allowing them to efficiently communicate with each other.
+
+---
+## Official Documentation
+For information about collage and its capabilities, please have a look at our [Official Documentation](https://sickag.github.io/collage/).
+
+---
+
+## Preview
+To create and embed micro frontends with collage you just need to add a few lines on top of your already existing Application:
+
+```html
+<body>
+  <div class="somewhere">
+    <!-- include a micro frontend effortlessly -->
+    <collage-fragment
+      src="/url/to/micro-frontend"
+      config-something="Configure this!"
+      name="my-micro-frontend">
+    </collage-fragment>
+  </div>
+</body>
+```
+
+
+```js
+const api = await expose({
+  // expose the api of your micro frontend
+  services: {
+    myService(name = "") {
+      return `Default Implementation for ${name}`;
+    },
+  },
+});
+
+```
+
+## Features
+- Upgrade any web application to a micro frontend by exposing its capabilities.
+- Embed micro frontends in your application.
+- Configure embedded micro frontends to fit them perfectly into your application.
+- Provide services to other micro frontends and the whole Arrangement and use services, other Contexts are exposing.
+- Publish messages or subscribe to topics which are available for all parts of your application.
+- Micro frontends built with different frameworks can be combined to one application without effort.
+- Scope Isolation Guarantees compatibility in every scenario.
+- Bundle micro frontends into your application at build time or include them from any other origin - they can even be added and removed dynamically at runtime.
+## Non-functional Features
+- Small - Minified and gzipped, its footprint is just about 15 KB.
+- Easy to use - Create a micro frontend with just a few lines of code.
+- Use a self explainatory api to describe your micro frontends and orchestrate them in complex arrangements effortlessly.
+- Built on web standards and only a few simple core concepts means that you never run into magic behaviour that ruins your day.
+- Easy to use - Simply wrap the expose() call to create custom functionality.
diff --git a/docs/docs/concepts.md b/docs/docs/concepts.md
@@ -74,8 +74,6 @@ It should also be designed in such a way, that a meaningful user interaction can
 
 ## (coming soon) Style Synchronization
 
-<!-- TODO: enable section when https://deagxjira.sickcn.net/jira/browse/DAVIAF-109 is done -->
-
 > *Comming Soon*
 >
 > The concept and Api descript here is NOT yet part of the current version of Collage. Is WILL however be implemented in the near future.