Improving documentation

Signed-off-by: Piotr <piotrzan@gmail.com>

README.md

@@ -7,35 +7,50 @@
 
 **Table of Contents**
 
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Requirements:](#requirements:)
-  - [Functionality:](#functionality:)
-  - [Example:](#example:)
-- [Disclaimer](#disclaimer)
-- [License](#license)
+* [Installation](#installation)
+* [Introduction](#introduction)
+* [Documentation](#documentation)
+  * [Requirements](#requirements)
+  * [Example usage](#example-usage)
+* [Disclaimer](#disclaimer)
+* [License](#license)
 
 ## Installation
 
 ```console
 pip install killercoda-cli
 ```
 
-## Usage
+> [!NOTE]
+>
+> If there is an installation permissions error [Error 13], consider installing
+> with `--user` flag or adding `./local/bin` to the `PATH` variable.
+
+## Introduction
+
+The interactive [killercoda] scenarios are a great way learn new technologies in
+an _hands-on_ approach. However, creating the scenarios and managing can be
+tedious and time consuming.
+
+The `killercoda-cli` solves some of those problems by:
 
-Pdoc generated Documentation available at: https://piotr1215.github.io/killercoda-cli/killercoda_cli/cli.html
+- Adding a new step after the existing last step and creating a directory for
+  including foreground and background scripts placeholders.
+- Renaming and re indexing step files and directories allowing for inserting a
+  step in between existing steps and moving content _down_
+- Updating the `index.json` file to reflect changes in step order and titles.
 
-### Requirements:
+## Documentation
 
-- The tool must be run in a directory containing step files or directories (e.g., step1.md, step2/).
-- An 'index.json' file must be present in the directory, which contains metadata about the steps.
+Autogenerated API documentation generated in [pdoc](https://pdoc.dev/docs/pdoc.html) available
+at: https://piotr1215.github.io/killercoda-cli/killercoda_cli/cli.html.
 
-### Functionality:
+### Requirements
 
-- Renames and renumbers step files and directories based on user input.
-- Updates the 'index.json' file to reflect changes in step order and titles.
+- The tool must be run in a directory containing step files or directories (e.g. step1.md, step2/).
+- An `index.json` file must be present in the directory, which contains metadata about the steps.
 
-### Example:
+### Example usage
 
 Suppose you have a scenario directory with the following structure:
 
@@ -45,9 +60,9 @@ Suppose you have a scenario directory with the following structure:
     └── step2
         └── step2.md
 
-And you want to insert a new step between 'step1.md' and 'step2/', titled "New Step".
+And you want to insert a new step between `step1.md` and `step2/`, titled "New Step".
 
-1. Run 'killercoda-cli'.
+1. Run `killercoda-cli`.
 2. Enter the title for the new step: "New Step".
 3. Enter the step number to insert the new step at: 2.
 
@@ -101,16 +116,14 @@ After:
 }
 ```
 
-> [!NOTE]
->
-> The tool automatically handles the renaming of directories and files, ensuring a smooth workflow for scenario development and updates.
-
 ## Disclaimer
 
 This is an my personal project to easier create and manage killercoda scenarios.
-Check out [killercoda](https://killercoda.com/) interactive scenarios to learn more about
+Check out [killercoda] interactive scenarios to learn more about
 the service.
 
 ## License
 
 `killercoda-cli` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
+
+[killercoda]: https://killercoda.com/