From 0d5009205066dded7e184737bc4a8de8839a7325 Mon Sep 17 00:00:00 2001
From: Jonas Eberle <flightvision@googlemail.com>
Date: Mon, 9 Nov 2020 17:11:48 +0100
Subject: [PATCH] [DOCS] update README

---
 README.md | 57 +++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 45 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index decc88e..5b89b7e 100644
--- a/README.md
+++ b/README.md
@@ -6,27 +6,60 @@ This API provides an easy and reliable way to register content blocks (composer
 See [Content Blocks Registration in TYPO3](https://github.com/TYPO3-Initiatives/structured-content/blob/master/Documentation/ContentBlocks/ContentBlockRegistration.md)
  for more information about content blocks.
 
-## Requirements
-* TYPO3 v10+
-* [Fluid based Page module](https://docs.typo3.org/c/typo3/cms-core/master/en-us/Changelog/10.3/Feature-90348-NewFluid-basedReplacementForPageLayoutView.html) (which is default in v10 and will be the only one in v11) is needed for
-backend preview
+### Status
+
+`alpha` - the main concepts are laid out but nothing is polished yet. We welcome your feedback.
+You can reach us in the TYPO3 Slack `#cig-structuredcontent-contentblockcreation` ❤️.
+
+## Installation
+
+### For developing on this API
+
+This will set up a TYPO3 v10 and install the API extension.
+
+It is a quickstart to explore the feature, too.
 
-## For developing this API
 1) clone this repository
 2) `ddev launch /typo3`
-   This will set up a TYPO3 v10, install the API extension and enable some example Content Blocks.
 
-## For using Content Blocks: Installation of the API extension into your TYPO3
+It includes example Content Blocks in a local composer that are installed by default.
+
+### For using Content Blocks
+
+#### Requirements
+* TYPO3 v10+
+* In TYPO3 v10, backend previews require the [Fluid based Page module](https://docs.typo3.org/c/typo3/cms-core/master/en-us/Changelog/10.3/Feature-90348-NewFluid-basedReplacementForPageLayoutView.html) to be enabled.
+
+This installs the API required to use content blocks.
+It consists of 2 composer packages: an API extension and a composer plugin.
 
+#### Installation steps
 <pre>
-composer config repositories.content-block-registration-api vcs https://github.com/TYPO3-Initiatives/content-block-registration-api.git
-composer config repositories.content-blocks-composer-plugin vcs https://github.com/TYPO3-Initiatives/content-blocks-composer-plugin.git
+composer config repositories.cb-api vcs https://github.com/TYPO3-Initiatives/content-block-registration-api.git
+composer config repositories.cb-composer-plugin vcs https://github.com/TYPO3-Initiatives/content-blocks-composer-plugin.git
 composer config minimum-stability dev
 composer req sci/sci-api:dev-master
 </pre>
 
 * Add new database fields: (Backend) `Maintenance` › `Analyze Database Structure`
-* Use composer to install Content Block packages or add them manually to `typo3conf/contentBlocks`
+
+### Getting/Creating new content blocks
+
+#### Via composer
+
+[This is an example repo](https://github.com/TYPO3-Initiatives/content-block-examples) with a content block
+<pre>
+composer config repositories.cb-examples vcs https://github.com/TYPO3-Initiatives/content-block-examples.git
+composer req sci/call-to-action-example:dev-master
+</pre>
+
+#### Wizard
+
+There is a wizard module that kickstarts Content Blocks for you.
+
+#### Create them locally
+
+You can also add a Content Block directory manually to `typo3conf/contentBlocks`.
 
 ## Usage
 
@@ -46,9 +79,9 @@ Following aspects are mandatory for a content block to be validated successfully
 - The backend language file `Default.xml` or `EditorInterface.xlf` has to be present in the `src/Language` folder of the package
 - The file `EditorPreview.html ` has to be present in the `src` folder of the package
 
-### Storage
+### Location
 
-The content block composer package it is stored in `typo3conf/contentBlocks/`.
+Content blocks are stored in or symlinked to `typo3conf/contentBlocks/`.
 
 ### Virtual generation of TCA