diff --git a/README.md b/README.md
index 859d624..271016e 100644
--- a/README.md
+++ b/README.md
@@ -24,8 +24,6 @@ npm install telebuilder
 
 Example of a bot built with TeleBuilder: [jekyll-post-bot](https://github.com/en9inerd/jekyll-post-bot)
 
-```typescript
-
 ### Configuration
 
 TeleBuilder uses a `ConfigService` to manage and load configuration settings for your bot. The service loads configuration files based on your environment and merges them to create a final, read-only configuration object that your application can use.
@@ -91,6 +89,16 @@ await client.init();
 
 ### Defining Commands
 
+Each command is a class that implements the `Command` interface and is decorated with the `@command` decorator.
+There are required properties and methods that you need to implement in your command class:
+- `command`: The command name that triggers the command.
+- `description`: A brief description of what the command does.
+- `scopes`: An array of `CommandScope` objects that define where the command and by whom it can be executed.
+- `langCodes`: An array of language codes for which the command is available.
+- `entryHandler`: The method that is called when the command is executed.
+
+Here is an example of a command class:
+
 ```typescript
 @command
 export class StartCommand implements Command {
@@ -102,6 +110,7 @@ export class StartCommand implements Command {
       peer: channelAuthor
     },
   ];
+  langCodes = [];
 
   @handler({
     event: {
@@ -116,8 +125,58 @@ export class StartCommand implements Command {
 
 ### Event/Update Handlers
 
+Event handlers are methods that are called when a specific event occurs. You can define event handlers for different types of events, such as new messages, edited messages, callback queries and other events supported by GramJS.
+To define an event handler, use the `@handler` decorator and provide the event type and any additional options that you want to apply to the handler. `@handler` decorator isn't required for command entry handlers.
+Example of an event handler:
+
+```typescript
+  @handler({
+    type: 'album',
+    event: {
+      chats: [channelId],
+      incoming: true,
+      outgoing: false,
+    },
+    validateCommandParams: false,
+    lock: false
+  })
+  @catchError()
+  public async getNewAlbum(event: AlbumEvent): Promise<void> {
+    // prevent edited messages from being processed
+    if (event.messages.length === 1 || !event?.client) return;
+
+    // process the album;
+  }
+```
+
 ### Command Parameters
 
+Commands can take parameters that are passed by the user when executing the command like `/command param1=value1 param2=value2`.
+
+You can define parameters for your commands using the `@params` decorator. The `@params` decorator takes an object that defines the parameters for the command. Each parameter is defined by a key-value pair where the key is the parameter name and the value is an object that defines the parameter schema. At the moment, the supported parameter types are `string`, `number`, `boolean`, and `enum`.
+
+Here is an example of how to define parameters for a command:
+
+```typescript
+  @params params: CommandParamsSchema = {
+    param1: {
+      type: 'string',
+      required: true,
+      default: '',
+    },
+    param2: {
+      type: 'number',
+      required: false,
+      default: 0,
+    },
+    param3: {
+      type: 'enum',
+      enamValues: ['value1', 'value2', 'value3'],
+      required: false,
+    },
+  };
+```
+
 ### Button Menus
 
 ### Dependency Injection