more explanation in README

README.md

@@ -2,6 +2,28 @@
 
 A simple python script used to decode and encode TOTP QR-Codes.
 
+## What is TOTP?
+TOTP is a a form of two factor authentication known as a 'Time based one time password'.
+Client and server have to both know a secret,
+from which they generate time-dependent (one-time) passcodes as a second factor.
+This is *not* an implementation of the TOTP protocol,
+many corresponding apps (e.g. [freeotp][FreeOTP]) or devices (e.g. [sct][Reiner SCT]) exist.
+
+## Why do I need this?
+Probably you don't, here the authors use-case is explained.
+
+Usually, these apps/devices scan the initial secret along with some metadata using a QR code
+that will be provided by the web-service when setting up 2FA.
+This script decodes those QR-codes, enabling plain text editing of them and re-builds QR codes.
+This way, fully-functional 2FA entries can be produced while allowing to edit metadata.
+
+Additionally, a high error-correction level is chosen to simplify scanning with your authenticator
+device/app.
+
+The author uses this as some websites don't set their metadata correctly
+(e.g. not setting a username, prohibiting distinguishing multiple accounts on the same website)
+or have names too long to be displayed conveniently.
+
 
 # Installation
 You need [zbar][zbar] as a QR-code reader library.
@@ -13,8 +35,15 @@ On Ubuntu, install `zbar-tools`.
 Additionally, you need `python3` and the `pip` packages listed in `requirements.txt`.
 
 
-
 # Usage
+Call the `totp.py` script. Input QR codes can be placed into the `in` folder
+(use screenshots for this).
+They will be parsed and their data extracted in `json` format in the `json` folder.
+You can then edit the `json` files to your willings.
+Calling the script again will produce new QR codes in the `out` folder which you
+can scan.
 
 
 [zbar]: https://github.com/mchehab/zbar
+[freeotp]: https://freeotp.github.io/
+[sct]: https://authenticator.reiner-sct.com/en/