docs: update documentaion

- README was really out-of-date at this point, so here is an update
- fixed few things here and there in the getting started section

Signed-off-by: AtomicFS <[email protected]>

README.md

@@ -1,23 +1,30 @@
-# Compile Firmware
+# Firmware-Action
 
 [![Lint](https://github.com/9elements/firmware-action/actions/workflows/lint.yml/badge.svg)](https://github.com/9elements/firmware-action/actions/workflows/lint.yml)
 [![pytest](https://github.com/9elements/firmware-action/actions/workflows/pytest.yml/badge.svg)](https://github.com/9elements/firmware-action/actions/workflows/pytest.yml)
 [![dagger](https://github.com/9elements/firmware-action/actions/workflows/docker-build-and-test.yml/badge.svg)](https://github.com/9elements/firmware-action/actions/workflows/docker-build-and-test.yml)
 [![go test](https://github.com/9elements/firmware-action/actions/workflows/go-test.yml/badge.svg)](https://github.com/9elements/firmware-action/actions/workflows/go-test.yml)
 
-This repository contains tools to simplify builds of firmware stacks.
+Firmware-Action is a tool to simplify building firmware. Think of it as `Makefile` or `Taskfile` but specifically for firmware. The tool it-self is written entirely in [Golang](https://go.dev/).
 
-At the moment it supports:
+Motivation behind the creation is to unify building of firmware across development environments. The goal of firmware action is to run on your local machine but also in your CI/CD pipeline, with the same configuration producing the same output.
+
+There is also a independent python tool to prepare Docker containers to be used with Firmware-Action. These are hosted in GitHub and are freely available (no need to build any Docker containers yourself).
+
+There is also a GitHub action integration allowing you to use Firmware-Action in your GitHub CI/CD.
+
+At the moment Firmware-Action supports:
 - [coreboot](https://coreboot.org/)
 - [linux](https://www.kernel.org/)
 - [tianocore / edk2](https://www.tianocore.org/)
 - firmware stitching (populating IFD regions with binaries)
+- [u-root](https://github.com/u-root/u-root)
 
 This list should expand in the future (see [issue 56](https://github.com/9elements/firmware-action/issues/56)).
 
-Motivation behind the creation is to unify building of firmware across development. The same code and configuration should run in CI/CD pipeline just as well as on your local machine.
+Firmware-Action is using [dagger](https://docs.dagger.io/) under the hood, which makes it rather versatile tool. When Firmware-Action is used, it automatically downloads user-specified Docker container in which it will attempt to build the firmware.
 
-Initially it was meant only as GitHub-specific action, but it should be universal thanks to [dagger](https://docs.dagger.io/).
+If your firmware consists of multiple components, such as `coreboot` with `linux` as payload, you can simply define each as module and define dependency between them. Each module is build separately, but can use output of another module as input. In the `coreboot` + `linux` example, you can call Firmware-Action to build `coreboot` recursively, which will also build `linux` due to the dependency definition. This way, you can build complex stacks of firmware in single call.
 
 [Documentation is hosted in pages](https://9elements.github.io/firmware-action/).
 

docs/src/firmware-action/get_started/01_repo.md

@@ -1,12 +1,12 @@
 # Start a new git repository
 
-Start a new repository in GitHub and the clone it.
+Start a new repository in GitHub and then clone it.
 
 
-## Add coreboot as submodule
+## Add coreboot as git submodule
 
 ```admonish tip
-Add git submodule with:
+To add git submodule, run:
 ~~~
 git submodule add <repo> <path>
 ~~~
@@ -17,11 +17,7 @@ Add [coreboot repository](https://review.coreboot.org/admin/repos/coreboot,gener
 git submodule add --depth=1 "https://review.coreboot.org/coreboot" coreboot
 ```
 
-```bash
-git submodule update --init
-```
-
-Optionally checkout a release tag, for example `4.19` (it is a bit older release from January 2023, but should suffice for demonstration)
+In this example we will work with coreboot `4.19` release (it is a bit older release from January 2023, but should suffice for demonstration)
 ```bash
 ( cd coreboot; git fetch origin tag "4.19"; git checkout "4.19" )
 ```
@@ -33,6 +29,6 @@ git submodule update --init --recursive
 ```
 
 ```admonish warning
-Recursively initializing all submodules in coreboot will take a moment.
+Recursively initializing all submodules in coreboot will take a minute or two.
 ```
 

docs/src/firmware-action/get_started/03_json_config.md

@@ -9,11 +9,11 @@ This configuration file is for firmware-action, so that it knows what to do and
 ~~~
 
 ```admonish info
-Field `repo_path` is pointing to the location of our coreboot submodule.
+Field `repo_path` is pointing to the location of our coreboot submodule which we added in previous step [Repository](01_repo.md).
 ```
 
 ```admonish info
-Field `defconfig_path` is pointing to the location of coreboot's configuration file.
+Field `defconfig_path` is pointing to the location of coreboot's configuration file which we created in previous step [coreboot configuration](02_coreboot_config.md).
 ```
 
 ```admonish info

docs/src/firmware-action/get_started/04_get_firmware_action.md

@@ -1,6 +1,7 @@
 # Get firmware-action
 
-Either [clone the repository and build the executable yourself](../usage_local.md), or just download pre-compiled executable from [releases](https://github.com/9elements/firmware-action/releases).
-
-For Arch Linux there is also a [AUR package](https://aur.archlinux.org/packages/firmware-action) available.
+You can get Firmware-Action multiple ways:
+- clone the repository and [build the executable yourself](../usage_local.md)
+- download pre-compiled executable from [releases](https://github.com/9elements/firmware-action/releases).
+- Arch Linux [AUR package](https://aur.archlinux.org/packages/firmware-action)
 

docs/src/firmware-action/get_started/05_run_firmware_action.md

@@ -6,9 +6,22 @@
 
 `firmware-action` will firstly download `registry.dagger.io/engine` container needed for dagger and start it.
 
-Then it will proceed to download `coreboot` container (specified by `sdk_url` in JSON config), copy into it specified files and then start compilation.
+Then it will proceed to download `coreboot` container {{footnote: The used container is specified by `sdk_url` in the firmware-action configuration file.}}, copy into it specified files and then start compilation.
+
+If compilation is successful, a new directory `output-coreboot/` will be created {{footnote: Output directory is specified by `output_dir` in firmware-action configuration file.}} which will contain files {{footnote: Output files are specified by `container_output_files` in firmware-action configuration file.}} and possibly also directories {{footnote: Directories to output are specified by `container_output_dirs` in firmware-action configuration file.}}.
+
+Your working directory should look something like this:
+```
+.
+|-- coreboot/
+|   `-- ...
+|-- firmware-action.json
+|-- output-coreboot/
+|   |-- coreboot.rom
+|   `-- defconfig
+`-- seabios_defconfig
+```
 
-If compilation is successful, a new directory `output-coreboot/` will be created (as specified by `output_dir` in JSON config) which will contain files (specified by `container_output_files` in JSON config) and possibly also directories (specified by `container_output_dirs` in JSON config).
 
 ```admonish info
 `container_output_dirs` and `container_output_files` are lists of directories and files to be extracted from the container once compilation finished successfully.

docs/src/firmware-action/get_started/get_started.md

@@ -15,4 +15,5 @@ The code from this example is available in [firmware-action-example](https://git
 
 - installed [Docker](https://wiki.archlinux.org/title/Docker)
 - installed git
+- installed [taskfile](https://taskfile.dev/) (optional)
 

docs/src/firmware-action/interactive.md

@@ -1,28 +1,24 @@
 # Interactive mode
 
-```admonish debugging
-Dagger [since v0.12](https://dagger.io/blog/dagger-0-12) supports new built-in interactive debugging. We are already planning to re-write `firmware-action` to use this new feature instead of the `ssh` solution we are currently using. For more details see issue [269](https://github.com/9elements/firmware-action/issues/269).
-```
-
 ```admonish note title="A little bit of backstory"
 While I was playing around with firmware-action I found early on that debugging what is going on inside the docker container is rather lengthy and annoying process. This was the moment when the idea of some interactive option was born.
 ```
 
-```admonish bug title="Issue [#109](https://github.com/9elements/firmware-action/issues/109)"
-```
+```admonish bug title="Issue [#269](https://github.com/9elements/firmware-action/issues/269)"
+Dagger [since v0.12](https://dagger.io/blog/dagger-0-12) supports new built-in interactive debugging.
 
-```admonish done title="Pull request [#147](https://github.com/9elements/firmware-action/pull/147)"
+We are already planning to re-write `firmware-action` to use this new feature instead of the `ssh` solution we are currently using. For more details see issue [269](https://github.com/9elements/firmware-action/issues/269).
 ```
 
 On build failure open `ssh` server in the container and let user connect into it to debug the problem. To enable this feature user has to pass argument `--interactive`. User can ssh into the container with a randomly generated password.
 
-The container will keep running until user presses `ENTER` key.
+The container will keep running until user presses `ENTER` key in the terminal with firmware-action running.
 
 
 ```admonish attention
 The container is launched in the interactive mode before the failed command was started.
 
-This reverting is out of technical necessity.
+This reverting behavior is out of technical necessity.
 ```
 
 ```admonish note