Restructure README to be clearer

README.md

@@ -4,6 +4,8 @@
 
 ## Overview
 
+re:scheduled is a web application for managing translation shifts at chaos events. It facilitates the coordination of translation angels, session scheduling, and real-time collaboration during events.
+
 ### Features
 
 - **Automatic schedule import** for re:publica, Pretalx/Hub
@@ -24,7 +26,7 @@
 - **Import history** with error tracking for conference data
 - ... and more 🎁
 
-### Technologies:
+### Technologies
 
 - [Ruby on Rails](https://rubyonrails.org/) with [SQLite](https://sqlite.org/) DB
 - [Tailwind CSS](https://tailwindcss.com/)
@@ -33,13 +35,15 @@
 - [Devise](https://github.com/heartcombo/devise) for authentication
 - [SolidQueue](https://github.com/rails/solid_queue) for background jobs
 
-## Dev environment
+## Getting Started
+
+### Development Environment
 
 The project comes with a devcontainer for VSCode and compatible editors. Simply open the project folder in Code (or using `devcontainer open <path>`) and after a few seconds, a suitable container should be ready.
 
 Run `bin/dev` in the integrated terminal to start the dev webserver and the tailwind watch job (see `Procfile.dev` for details). Access your local re:scheduled at http://127.0.0.1:3000.
 
-## Secrets
+### Secrets Configuration
 
 The application requires some secrets, as of writing these include:
 
@@ -51,21 +55,35 @@ The application requires some secrets, as of writing these include:
 
 You can supply the secrets by running `rails credentials:edit` or pass them as environment variable in upper case (e.g. `FILEDROP_USER`).
 
-## User and Role Management
+### Helpful Rails Tasks
+
+By running `bin/rails <command>` you can trigger some helpful actions, such as:
+
+- `rails c[onsole]`: Start interactive ruby shell
+- `rails db`: Start sqlite shell with the currently used DB
+- `rails db:prepare`: Create and migrate the database
+- `rails db:migrate`: Run pending DB migrations, automatically done by docker image on start
+- `rails db:seed` (Re-)import DB seeds from `db/seeds.rb`
+- `rails secret` generate a random secret, e.g. for `secret_key_base`
+- `rails generate` Powerful tool to generate boilerplate, run it to see list of options
+
+## Administration
+
+### User and Role Management
 
 The application uses a role-based access control system with the following main roles:
 - `admin`: Full system access
 - `events_admin`: Can manage conferences and related resources
 - `shift_coordinator`: Can manage session assignments
 
-### Managing Roles through the Admin UI
+#### Managing Roles through the Admin UI
 
 Roles can be managed through the admin interface:
 1. Navigate to `/admin/roles` to view all available roles
 2. Click on a role to edit its permissions
 3. To assign roles to users, navigate to `/admin/users` and edit the user
 
-### Managing Roles with Rake Tasks
+#### Managing Roles with Rake Tasks
 
 You can also use the following rake tasks to manage user roles from the command line:
 
@@ -87,9 +105,9 @@ rake admin:remove_events_admin[user@example.com]
 rake admin:remove_shift_coordinator[user@example.com]
 ```
 
-## Conference Management
+### Conference Management
 
-### Adding a New Conference
+#### Adding a New Conference
 
 Conferences can be added through the admin interface:
 1. Navigate to `/admin/conferences`
@@ -99,7 +117,7 @@ Conferences can be added through the admin interface:
 5. Provide the required data fields for the selected import method
 6. Save the conference to initiate the data import
 
-### Importing and Updating Conference Data
+#### Importing and Updating Conference Data
 
 Conference data can be imported and updated through the admin interface:
 1. Navigate to the conference details page in admin
@@ -107,7 +125,7 @@ Conference data can be imported and updated through the admin interface:
 3. The import process runs in the background with real-time progress tracking
 4. View the import history to see past imports and any errors
 
-### Setting Relevant Stages
+#### Setting Relevant Stages
 
 The admin interface provides a dedicated page for managing which stages are relevant:
 1. Navigate to the conference details page in admin
@@ -115,7 +133,7 @@ The admin interface provides a dedicated page for managing which stages are rele
 3. Check the boxes for stages that should be considered relevant
 4. Save your selection
 
-### Prioritizing Stages
+#### Prioritizing Stages
 
 You can set the display order of stages through stage weights. Higher weights push stages down in the listing order:
 
@@ -125,39 +143,63 @@ Stage.where(name: "Saal GLITCH").update(weight: 20)
 Stage.where(name: "Saal ZIGZAG").update(weight: 30)
 ```
 
-## In production
+## Daily Operations
 
-See [rescheduled-deploy](https://git.cccv.de/c3lingo/rescheduled-deploy) for a full docker-compose stack and more explanations.
+### Assignment Management
 
-# Colors (darkmode)
+Assignments can be created and managed through the web interface:
+1. Navigate to a session page
+2. Click on the "+" button next to an available slot to assign an angel
+3. The assignment is created in real-time and visible to all users
 
-- **text**: text-slate-300
-- **text (overlay)**: text-slate-200
-- **text light**: text-slate-400
+### Candidate Management
 
-- **logo**: text-white
-- **highlight**: text-red-500
+Angels can express interest in sessions:
+1. Navigate to a session page
+2. Click on "Express Interest" to mark yourself as a candidate
+3. Optionally add a note with additional information
+4. Shift coordinators can view and manage candidates from the session page
 
-- **dark background**: bg-zinc-700
-- **light background**: bg-gray-900
-- **overlay**: bg-gray-600
-- **input**: bg-zinc-900
-- **shadow**: gray-400
+### Notification System
 
-## Tips and Tricks
+The system can notify users about important events:
+- Assignment notifications
+- Schedule changes
+- Upcoming session reminders
 
-### Helpful `rails` tasks
+## Advanced Features
 
-By running `bin/rails <command>` you can trigger some helpful actions, such as
+### Integration with External Systems
 
-- `rails c[onsole]`: Start interactive ruby shell
-- `rails db`: Start sqlite shell with the currently used DB
-- `rails db:migrate`: Run pending DB migrations, automatically done by docker image on start
-- `rails db:seed` (Re-)import DB seeds from `db/seeds.rb`
-- `rails secret` generate a random secret, e.g. for `secret_key_base`
-- `rails generate` Powerful tool to generate boilerplate, run it to see list of options
+#### Filedrop Integration
+
+Documents related to sessions can be managed via the Filedrop integration:
+1. Navigate to a session's detail page
+2. Click on the "Filedrop" tab to see related documents
+3. Documents can be uploaded, viewed, and commented on
+
+#### Engelsystem Integration
+
+Sessions can be synchronized with the Engelsystem:
+1. Navigate to a session's detail page
+2. Click on "View in Engelsystem" to open the corresponding shift
+3. Changes in assignments can be synchronized between systems
+
+#### Telegram Notifications
+
+Important events can trigger Telegram notifications:
+- Use the notification settings to configure which events trigger notifications
+- Group chats can receive consolidated updates
+
+## Deployment
 
-### In `rails console`
+### Production Environment
+
+See [rescheduled-deploy](https://git.cccv.de/c3lingo/rescheduled-deploy) for a full docker-compose stack and more explanations.
+
+### Maintenance Tasks
+
+Some helpful maintenance tasks you can run in the Rails console:
 
 - Reset user password
   ~~~ruby
@@ -180,6 +222,25 @@ By running `bin/rails <command>` you can trigger some helpful actions, such as
   Candidate.includes(:user, :session).where.not(note: [nil, ""]).pluck('sessions.title','users.name', :note)
   ~~~
 
+## Appendix
+
+### UI Styling Reference
+
+#### Colors (darkmode)
+
+- **text**: text-slate-300
+- **text (overlay)**: text-slate-200
+- **text light**: text-slate-400
+
+- **logo**: text-white
+- **highlight**: text-red-500
+
+- **dark background**: bg-zinc-700
+- **light background**: bg-gray-900
+- **overlay**: bg-gray-600
+- **input**: bg-zinc-900
+- **shadow**: gray-400
+
 ## License
 
 re:scheduled is licensed under the GNU Affero General Public License, Version 3.
\ No newline at end of file