From 02a75b7d5388f5415dd0e9b61958bc25da66b5e8 Mon Sep 17 00:00:00 2001
From: Mysh! <me@mysh.dev>
Date: Sat, 25 Jan 2025 23:21:22 +0300
Subject: [PATCH] refactor(README): better description of the project

---
 README.md | 58 +++++++++++++++++++++++++++++++------------------------
 1 file changed, 33 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index 938c4e4..ba9811c 100644
--- a/README.md
+++ b/README.md
@@ -1,50 +1,58 @@
-![Maddy password reset service logo](https://user-images.githubusercontent.com/44648612/218335570-cdb3ba2f-4ff9-43ee-bd43-f892c644b153.png)
+![Project Banner](https://user-images.githubusercontent.com/44648612/218335570-cdb3ba2f-4ff9-43ee-bd43-f892c644b153.png)
 
-# Maddy password reset service
+# Maddy Password Reset Service
 
-Runs an HTTP server that serves password reset form.
+Runs an HTTP server that serves a password reset form. 
+It should be installed on the same server where Maddy is running.
 
-Still Work In Progress! And so no LICENSE file is provided. It will be here eventually.
+## How It Works
+
+It runs the `maddy creds password -p` command to change a user's password.
+
+### Use Cases
+
+- You are currently logged into your mailbox and want to reset the password.
+    - For example, you registered a user, and the user wants to change their password.
 
 ## Installation
 
-For the time being, you have to compile it yourself. 
-In the future there will be prebuilt binaries.
+For the time being, you need to compile it yourself.
 
 ### Requirements
 
 - Go
-- Maddy
+- Maddy (on the server, we need its CLI)
+
+To build this project, install `Go` and execute the following command:
 
-To build this project install `Go` and execute this:
 ```shell
 go build ./main.go
 ```
 
-Make sure to configure it first! First compilation will take moderate amount of time.
+Make sure to configure it first! The first compilation will take a moderate amount of time.
 
 ## Configuration
 
-By default, the web server starts on `:1323'. Make sure you hide it behind a reverse proxy.
+By default, the web server starts on `:1323`. Make sure you hide it behind a reverse proxy.
 
-You will probably need to edit the `reset.gohtml` template to suit your needs.
+You will probably need to edit the `reset.gohtml` template to suit your needs. 
 For now, it contains a reset page in Russian for my hobby mail service.
 
-The only way to change the configuration is to change the consts in the `main.go` file:
+The only way to change the configuration is to modify the constants in the `main.go` file:
 
-- `MaddyPath` - path to maddy's database, e.g.: `/var/lib/maddy/credentials.db`
-- `HostingURL` - your domain name, for example: `http://localhost:1323/`
-- `SMTPMailUsername` - your full email address, for example: `robot@local.host`
-- `SMTPMailPassword` - your mailbox password
-- `SMTPMailHostname` - your mail hostname, for example: `mx1.local.host`
-- `MXServer` - your mail `MX` entry + `PORT`, for example: `mx1.local.host:587`
-- `EmailFrom` - the `$FROM` section of an EmailTemplate, for example: `robot@local.host`
-- `EmailSubject` - the `$SUBJECT` section of an EmailTemplate
-- `EmailMessage` - the `$MESSAGE` section of an EmailTemplate. Remember to provide a password reset link for a user `$RESET_LINK`. For example: `Here's your reset link: $RESET_LINK\r\n`
-- `EmailTemplate`- your reset email message
-- `HTTPServerPort` - HTTP server port
+- `MaddyPath` – Path to Maddy's database, e.g., `/var/lib/maddy/credentials.db`
+- `HostingURL` – Your domain name, for example: `http://localhost:1323/`
+- `SMTPMailUsername` – Your full email address, for example: `robot@local.host`
+- `SMTPMailPassword` – Your mailbox password
+- `SMTPMailHostname` – Your mail hostname, for example: `mx1.local.host`
+- `MXServer` – Your mail `MX` entry and `PORT`, for example: `mx1.local.host:587`
+- `EmailFrom` – The `$FROM` section of an email template, for example: `robot@local.host`
+- `EmailSubject` – The `$SUBJECT` section of an email template
+- `EmailMessage` – The `$MESSAGE` section of an email template. Remember to provide a password reset link for the user using `$RESET_LINK`. For example: `Here's your reset link: $RESET_LINK\r\n`
+- `EmailTemplate` – Your reset email message
+- `HTTPServerPort` – HTTP server port
 
-`EmailTemplate` example:
+### `EmailTemplate` Example
 
 ```text
 "To: $TO\r\n" +
@@ -53,4 +61,4 @@ The only way to change the configuration is to change the consts in the `main.go
 "Subject: $SUBJECT\r\n" +
 "\r\n" +
 "$MESSAGE\r\n"
-```
\ No newline at end of file
+```