diff --git a/README.md b/README.md
index 7eb2f6f8a1d53e72a05678622e9c8dd6fbd42a3b..ce730c4dcdaaf4d4303776ddee5b3bd119cbec80 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,25 @@
-# spotify
+# Spotify playlist generator
 
-# Register app
+Create fresh playlists from selected top played artists or existing playlists.
 
-<https://developer.spotify.com/dashboard/applications>
+Playlists are generated as public Spotify playlists, with 50 tracks (~3 hours), from your personal Spotify recommendations.
 
-App name:
-    Spotify playlist manager
+## Generate fresh playlist form artists
 
-Add description:
-    Application to help create/update playlists from other playlists or selected artists/tracks.
-    Something like "radios", but more personalized.
+From the list of your top played artists.
 
-Client ID:
-    41597dbeb0b3403caa28e7e428e0c9b2
+-   pick one or several artists in list
+-   click on "generate"
+-   a fresh playlist is generated with recommendations from each artist in pick ones
 
-Client Secret:
-    <hidden>
+You can choose if you want all recommendations, or only the ones with picked artists.
+
+A direct button can help to randomly pick artists.
+
+## Generate fresh playlist from existing playlists
+
+-   pick one or several playlist in list
+-   click on "generate"
+-   a fresh playlist is generated with recommendations from each track in picked playlists
+
+You can choose if you want all recommendations, or only the ones with artists in picked playlists.
diff --git a/SPOTIFY.md b/SPOTIFY.md
new file mode 100644
index 0000000000000000000000000000000000000000..e78db745417ab2cded5bf1bd6ec0a86d46b30e94
--- /dev/null
+++ b/SPOTIFY.md
@@ -0,0 +1,16 @@
+## Register app
+
+<https://developer.spotify.com/dashboard/applications>
+
+App name:
+    Spotify playlist manager
+
+Add description:
+    Application to help create/update playlists from other playlists or selected artists/tracks.
+    Something like "radios", but more personalized.
+
+Client ID:
+    41597dbeb0b3403caa28e7e428e0c9b2
+
+Client Secret:
+    <hidden>