TYPO3BestPractices · Schira-N · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026
diff --git a/Documentation/ForCodeExplorers.rst b/Documentation/ForCodeExplorers.rst
@@ -0,0 +1,16 @@
+.. include:: /Includes.rst.txt
+
+.. _forCodeExplorers:
+
+==================
+For Code-Explorers
+==================
+
+Your use case: you just want to have a look into the code and find examples of best-practices.
+
+The easiest way is to head to github and inspect the code online:
+
+.. code-block:: php
+
+  https://github.com/TYPO3BestPractices/tea
+
diff --git a/Documentation/Environment.rst → Documentation/ForContributors.rst b/Documentation/Environment.rst → Documentation/ForContributors.rst
@@ -1,40 +1,62 @@
 .. include:: /Includes.rst.txt
 
-.. _development-environment:
+.. _forContributors:
 
-=======================
-Development environment
-=======================
+================
+For Contributors
+================
 
-You can run the code quality checks and automated tests locally (using a
-local PHP, Composer, and database) or using runTests.sh.
+Your use case: You might want to contribute to the tea-extensions.
+You want to run the code quality checks and automated tests locally (using a
+local PHP, Composer, and database).
 
-To kickstart the project, we suggest the usage of the
+
+.. _clone:
+
+Cloning the distribution
+========================
+
+To use the full functionality of the tea-extension, you need a surrounding
+TYPO3-installation. You might take any installation for that, but we suggest the usage of the
 `TYPO3-testing-distribution <https://github.com/oliverklee/TYPO3-testing-distribution/>`__
 by Oliver Klee as development environment. The distribution comes with a frontend,
 example data and predefined plugins.
 
-The following commands expect that your SSH key is known by GitHub. If not, you need to use `https://`.
+
+The following commands expects that you have a GitHub-account and added your SSH key.
 
 .. index:: Clone TYPO3 Testing Distribution
 .. code-block:: bash
 
    git clone git@github.com:oliverklee/TYPO3-testing-distribution.git
 
-Please checkout the branch for the TYPO3 version you need. e.g. `12.x`.
+Without GitHub-account, clone via https:
+
+.. code-block:: bash
+
+   git clone https://github.com/oliverklee/TYPO3-testing-distribution.git
+
+
+Please check out the branch corresponding to your required TYPO3 version, for example 12.x.
+
 For more information about the TYPO3-testing-distribution (e.g. backend user credentials), use the documentation:
 https://github.com/oliverklee-de/TYPO3-testing-distribution/blob/13.x/README.md (TYPO3 13)
-Adjust link to your needed version.
 
+Again, adjust the link to the required TYPO3 version.
+
+.. _clone-tea:
+
+Cloning the tea extension
+=========================
 
+In the same way clone the tea extension.
 
 .. index:: Clone Tea Extension
 .. code-block:: bash
 
    git clone git@github.com:TYPO3BestPractices/tea.git
 
-You can organize the folder structure as you wish, but lets say your folder
-structure looks like this:
+You can organize the folder structure as you wish. It might look similar to this:
 
 .. index:: Folder structure
 .. code-block:: bash
@@ -52,17 +74,22 @@ Inside the testing distribution there is a file
 
     cp .ddev/docker-compose.extensions.yaml.template .ddev/docker-compose.extensions.yaml
 
-The file needs to mount the tea extension into the testing distribution. Keep in mind
-that you use the correct paths here.
-
+The file mounts the tea extension into the testing distribution. Make sure to insert the correct paths here.
 
 .. index:: Mount extension into testing distribution
 .. code-block:: yaml
 
     services:
       web:
         volumes:
-          - "$HOME/git/tea:/var/www/html/src/extensions/tea:cached,ro"
+          - "<PATH/TO/TEA/EXTENSION>/tea:/var/www/html/src/extensions/tea:cached,ro"
+
+Other volumes can safely be deleted.
+
+.. _start-testing-distribution:
+
+Start the testing distribution
+==============================
 
 After that you can start the testing distribution using ddev.
 

diff --git a/Documentation/ForLiveExplorers.rst b/Documentation/ForLiveExplorers.rst
@@ -0,0 +1,52 @@
+.. include:: /Includes.rst.txt
+
+.. _forLiveExplorers:
+
+==================
+For Live-Explorers
+==================
+
+Your use case: You are developing your own extension and want to add tests to improve your code quality.
+
+.. _preparation:
+
+Preparation
+===========
+
+Checkout your own extension.
+
+In the composer.json of your extension add the following parts of the composer.json of the tea-extension:
+
+* require-dev
+* scripts
+* scripts-descriptions
+
+From the config-section of tea-extension, copy these two lines:
+
+* "vendor-dir": ".Build/vendor"
+* "bin-dir": ".Build/bin",
+
+Copy the folder "Build" (not: ".Build"!) from tea-extension into your extension.
+
+Merge .gitignore from tea-extension into your extension.
+
+.. _run-tests:
+
+Run Tests
+=========
+
+After preparation run:
+
+.. code-block:: bash
+
+  ./Build/Scripts/runTests.sh -s composer up -W
+
+Composer should load a long list of dev-dependencies.
+
+Then use the testing commands. E.g.
+
+.. code-block:: bash
+
+  ./Build/Scripts/runTests.sh -s composer check:php:stan
+
+
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -43,7 +43,9 @@ checks, unit/functional/acceptance testing and continuous integration (CI).
    :titlesonly:
 
    Introduction
-   Environment
+   ForCodeExplorers
+   ForLiveExplorers
+   ForContributors
    TechnicalBackground
    DivergencesToTypo3Core
 

diff --git a/Documentation/Introduction.rst b/Documentation/Introduction.rst
@@ -17,10 +17,15 @@ checks, unit/functional/acceptance testing and continuous integration (CI).
 
 .. note::
 
-   This is not a kickstarter extension.
+   **Never run this extension in production!**
+
+   This extension has educational and documentational purpose only. It is never
+   meant to run in production.
+
+   This is also not a kickstarter extension.
+   It should not be used to kickstart other extensions.
+   Instead, it should serve as an example for best practices.
 
-   This extension should not be used to kickstart other extensions.
-   Instead, this extension should serve as an example for best practices.
 
 .. _why-is-this-extension-called-tea:
 
@@ -29,7 +34,7 @@ Why is this extension called "tea"?
 
 This extension aims to cover all fundamental aspects of developing an Extbase
 extension. The fictional use case is the management of tea varieties. The
-required models, classes, controllers, and other components represent all
+required models, classes, controllers and other components represent all
 typical parts of an Extbase extension. Additional examples demonstrate how to
 test these components.
 
@@ -44,11 +49,14 @@ This is not related to the `tea package manager <https://tea.xyz/>`__.
 Target group
 ============
 
-The target group for this extension is **TYPO3 extension developers**. Typical use
-cases include:
+The target group for this extension is **TYPO3 extension developers**.
+
+Typical use cases include:
 
-- Gaining inspiration by exploring the code
-- Cloning the tea extension locally to access a working example of tests, which can then be adapted for your own extension
+- Gaining inspiration by exploring the code :ref:`("see the code") <ForCodeExplorers>`
+- Installing the tea-extension without tests to have a simple but comprehensive example at hand ("install the tea extension")
+- Using the tests provided by tea extension to improve the code of your own extension :ref:`("use the tests") <ForLiveExplorers>`
+- Contributing to the collection of best practices by improving the tea-extension :ref:`("contribute to tea-extension") <ForContributors>`
 
 
 .. _presentation-online-days-2021: