fix: blocks docs

Author: marcinkrasowski

apps/docs/docs/main-components/blocks/customizing.md

@@ -4,8 +4,28 @@ sidebar_position: 300
 
 # Customizing
 
-While each block can have some basic configuration (like choosing a UI variant via props, or providing different text labels), that might not be enough for you. For cases where you'd like to perform more deep customizations, like adding new elements,
+While each block can have some basic configuration (like choosing a UI variant via props, or providing different text labels), that might not be enough for you. For cases where you'd like to perform more deep customizations, like adding new elements or modifying the layout, there is also the possibility to completely take over the ownership of the block - you can easily move its entire source code to your own project.
 
 ## Ejecting a block
+
+To _eject_ a block from the version that is published to NPM, you can run a dedicated script:
+
+```shell
+npm run eject-block
+```
+
+which will then prompt you for to the blocks you want to take over. Once the process is done, the code of these blocks will be copied to your project into the `packages/blocks` folder, and automatically install their dependencies.
+
+Once you restart the app, it will now use the ejected version of these blocks, instead of ones installed earlier via NPM.
+
 ## Modifying a block
+
+Since you now control the entire source code of the block, customizing it is easy. You can make any changes you want directly in that block, just like you'd do that when you create a new block from scratch yourself.
+
+These changes may include all parts of the block - the API Harmonization, the Frontend, and SDK areas.
+
 ## Upgrades & versioning
+
+This comes with a slight drawback, however - after you eject a block, you can no longer easily upgrade it to a newer version that might be published to the NPM registry. These new versions may include bugfixes or new features that you also might want.
+
+You can still achieve that, by simply running the eject script once more - it will **overwrite your own changes** to the block. However, assuming you are using any kind of code versioning, you can then pick and choose the changes you want to keep.

apps/docs/docs/main-components/blocks/index.md

@@ -4,9 +4,67 @@ sidebar_position: 000
 
 # Blocks
 
-> TODO: what is a block
+Blocks are designed to provide a modular and efficient approach to building feature-rich applications with minimal effort. Essentially, a block is a reusable, self-contained unit of functionality that combines harmonizing and frontend components into a single package.
+
+At their core, blocks are standalone modules that contain everything required to add a specific feature or functionality to your app. Each block is independently packaged as an NPM module and includes three primary parts:
+
+1. **API Harmonization Module:** Handles data aggregation, normalization, and exposes an API for that block.
+2. **Frontend Components:** React-based implementations that render the block's UI, including server and client components.
+3. **SDK Methods:** Simplified access to the block's API, designed for use internally within the block or externally by developers.
+
+Each block is a self-contained unit consolidating the logic for both data fetching and rendering, allowing independent development, maintenance, and upgrades.
+
+## Purpose of blocks
+
+The primary purpose of blocks is to enhance **developer productivity** and **consistency** across applications by creating reusable building blocks for key functionalities. Here’s how blocks fulfill this purpose:
+
+- **Modularity:** Each block is a fully isolated unit, allowing developers to quickly add or remove functionality without impacting other components of the application.
+- **Reusability:** Blocks are designed to work independently, making it easy to reuse them across multiple projects.
+- **Ease of Customization:** Blocks can be easily customized to fit the needs of a specific project while keeping the base package upgradable.
+- **Scalability:** By decoupling concerns and encapsulating logic, blocks simplify scaling and adding features to applications.
+
+## How can blocks help you
+
+Blocks bring several advantages for developers, simplifying and accelerating the app development process:
+
+1. **Streamlined Development**
+
+    Blocks encapsulate both frontend and backend code for a feature. You can simply install and integrate pre-built blocks to their app, avoiding the need to write these functionalities from scratch.
+
+2. **Ease of Integration**
+
+    Blocks can be installed with a single command as NPM packages and then easily imported into both the API Harmonization server and Frontend app.
+
+3. **Customization Support**
+
+    You can customize blocks to match your app's requirements while retaining the ability to receive updates from the base package.
+
+4. **Consistency Across Projects**
+
+    Using block-based architecture encourages consistent code patterns and practices across teams and projects.
+
+5. **Focus on Business Logic**
+
+    With most of the repetitive work taken care of by blocks, you can focus more on solving business-related problems instead of spending time implementing boilerplate functionality.
+
+6. **Encourages Collaboration**
+
+    Blocks allow you to work on individual pieces of functionality without interfering with or breaking other parts of the application.
+
+## How blocks fit into your app
+
+Each block provides both API handling and UI and rendering logic functionalities. Once installed:
+
+- **API Harmonization** ensures the block's necessary APIs are exposed and available in the API Harmonization server.
+- **Frontend** renders the block in the application's interface, fetching any required data and managing its internal logic.
+
+For example:
+
+- If you add an "FAQ" block, its frontend renderer displays a list of FAQs in your app, while its backend handles fetching the content.
+- You can easily extend this block to fit their design or content needs while utilizing the same robust base implementation.
 
 ## What’s inside?
+
 - **[Structure](./structure.md)** – Learn how the blocks are structured in the monorepo.
 - **[Usage](./usage.md)** – Understand how to work with blocks and how to add a new one.
 - **[Customizing](./customizing.md)** – Find out how you can customize an existing block in your own project and how the upgrades work.