4 files changed, 59 insertions, 28 deletions
diff --git a/docs/en/developers/01_First_steps.md b/docs/en/developers/01_First_steps.md
index dd56a6af6..7b3a4c11f 100644
--- a/docs/en/developers/01_First_steps.md
+++ b/docs/en/developers/01_First_steps.md
@@ -57,7 +57,7 @@ The `TAG` variable can be anything (e.g. `local`). You can target a specific arc
 
 # Project architecture
 
-**TODO**
+- the PHP framework: [Minz](Minz/index.md)
 
 # Extensions
 
diff --git a/docs/en/developers/03_Backend/02_Minz.md b/docs/en/developers/03_Backend/02_Minz.md
deleted file mode 100644
index cfbea15fe..000000000
--- a/docs/en/developers/03_Backend/02_Minz.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# Models
-
-**TODO**
-
-# Controllers and actions
-
-**TODO**
-
-# Views
-
-**TODO**
-
-# Routing
-
-**TODO**
-
-# Writing URL
-
-**TODO**
-
-# Internationalisation
-
-**TODO**
-
-# Understanding internals
-
-**TODO**
diff --git a/docs/en/developers/Minz/index.md b/docs/en/developers/Minz/index.md
new file mode 100644
index 000000000..9b6d46f17
--- /dev/null
+++ b/docs/en/developers/Minz/index.md
@@ -0,0 +1,19 @@
+# Minz
+
+Minz is the homemade PHP framework used by FreshRSS.
+
+The documentation is still incomplete and it would be great to explain:
+
+- routing, controllers and actions
+- configuration
+- models and database
+- views
+- URLs management
+- sessions
+- internationalisation
+- extensions
+- mailer
+
+Existing documentation includes:
+
+- [How to manage migrations](migrations.md)
diff --git a/docs/en/developers/Minz/migrations.md b/docs/en/developers/Minz/migrations.md
new file mode 100644
index 000000000..6cc985c22
--- /dev/null
+++ b/docs/en/developers/Minz/migrations.md
@@ -0,0 +1,39 @@
+# How to manage migrations with Minz
+
+Migrations are the way to modify the database or the structure of files under the `data/` path.
+
+## How to write a migration?
+
+Migrations are placed under the `app/migrations` folder.
+
+Good practice is to prepend the filename by the current date and explain what does the migration do in few words (e.g. `2020_01_11_CreateFooTable.php`).
+
+The files must contain a class which name starts with `FreshRSS_Migration_`, followed by the basename of the file (e.g. `FreshRSS_Migration_2020_01_11_CreateFooTable`).
+
+The class must declare a `migrate` static function. It must return `true` or a string to indicate the migration is applied, or `false` otherwise. It can also raise an exception: the message will be used to detail the error.
+
+Example:
+
+```php
+// File: app/migrations/2020_01_11_CreateFooTable.php
+class FreshRSS_Migration_2020_01_11_CreateFooTable {
+	public static function migrate() {
+		$pdo = new MinzPDOSQLite('sqlite:/some/path/db.sqlite');
+		$result = $pdo->exec('CREATE TABLE foos (bar TEXT)');
+		if ($result === false) {
+			$error = $pdo->errorInfo();
+			raise Exception('Error in SQL statement: ' . $error[2]);
+		}
+
+		return true;
+	}
+}
+```
+
+## How to apply migrations?
+
+They are automatically applied one by one when a user accesses FreshRSS.
+
+Before being applied, migrations are sorted by filenames (see the [`strnatcmp`](https://php.net/strnatcmp) function). Already applied migrations are skipped (the list can be found in the `data/applied_migrations.txt` file).
+
+To ensure migrations are not applied several times if two users access FreshRSS at the same time, a folder named `data/applied_migrations.txt.lock` is created, then deleted at the end of the process.