improve readme

README.md

@@ -2,6 +2,10 @@
 
 `crem` stands for **c**ompositional **r**epresentable **e**xecutable **m**achines
 
+It allows creating state machines (Mealy machines in fact), compose them to build bigger machines out of smaller ones and then run them and draw their flow and their state space.
+
+Further documentation can be found in the [docs](/docs) folder.
+
 ## development
 
 This is a Haskell Cabal project that uses Nix for development. Nix is optional but recommended.
@@ -62,7 +66,9 @@ nix build -L .#crem.ghc92
 
 ## project setup
 
-- `flake.nix`
+In this section we document all the files relevant for the project setup.
+
+### `flake.nix`
 
 This file specifies our project's dependencies and outputs/artefacts.
 Some common dependencies for a Haskell project are the GHC and Cabal, but during development we also use HLS, hpack, ....
@@ -73,12 +79,12 @@ It also allows us to create other controlled environments, such as container ima
 
 The project should still build without Nix, because Nix does not change any project files. This means you must have Cabal and system libraries installed manually.
 
-- `flake.lock`
+### `flake.lock`
 
 This file is automatically generated and updated by Nix, when evaluating the `flake.nix` file.
 It contains the timestamps and hashes of each input at the time of last update.
 
-An input coupled with a timestamp and hash of its contents is called a *pinned* input. Pinning inputs allows us to gurantee reproducibility.
+An input coupled with a timestamp and hash of its contents is called a *pinned* input. Pinning inputs allows us to guarantee reproducibility.
 
 We can specify unpinned inputs in `flake.nix`; for example, our `nixpkgs` input is not pinned to a specific commit. The branch `nixpkgs-unstable` changes almost every day.
 However, the `flake.lock` file contains a timestamp and hash of a specific commit in the `nixpkgs` repository. This is regenerated for every input every time we run `nix flake upadate`, to the latest commit in the branch/tag we specified in the flake.
@@ -89,21 +95,21 @@ One way of doing this is with the command:
 nix build . --update-input nixpkgs
 ```
 
-- `shell.nix`
+### `shell.nix`
 
 Nix flakes are a new feature. Some Nix installations do not support them. However, it is still useful to provide a development shell for developers with older Nix versions.
 
-This file allows us to replicate the development shell provided in `flake.nix` without duplicating the code. This way changes to the `flake.nix` are automaticaly propagated to the `shell.nix`.
+This file allows us to replicate the development shell provided in `flake.nix` without duplicating the code. This way changes to the `flake.nix` are automatically propagated to the `shell.nix`.
 
 Some tools also don't yet support flakes. An important example is Visual Studio Code with the Nix Environment Selector plugin: it works with `shell.nix`, but not `flake.nix`.
 
-- `hie.yaml`
+### `hie.yaml`
 
 This file instructs the Haskell Language Server how your project should be built. Find more information at [https://haskell-language-server.readthedocs.io/en/latest/configuration.html](https://haskell-language-server.readthedocs.io/en/latest/configuration.html).
 
-- `package.yaml`
+### `package.yaml`
 
-This file contains the Cabal package specification in Yaml format read by Hpack. It is more abstract and easier to maintain than the Cabal file format.
+This file contains the Cabal package specification in `yaml` format read by [hpack](https://github.com/sol/hpack#readme). It is more abstract and easier to maintain than the Cabal file format.
 
 To generate a `.cabal` file from a `package.yaml` file, run the following command:
 ```sh
@@ -113,16 +119,14 @@ hpack
 Note that Cabal does not understand `package.yaml` files, and requires us to generate a `.cabal` file before running `cabal`.
 Nix (or more precisely, Cabal2nix) uses a `.cabal` file if it is present, otherwise the `package.yaml` file. Because `package.yaml` is our single source of truth, we would prefer that Nix uses it instead of the generated `.cabal`. This is why we don't commit the `.cabal` file.
 
-- `crem.cabal`
+### `crem.cabal`
 
 This file is automatically generated from the `package.yaml` file and should not be committed to Git history.
 
-### tool-specific files
-
-- `fourmolu.yaml`
+### `fourmolu.yaml`
 
 Configuration file for the [`fourmolu`](https://github.com/fourmolu/fourmolu) formatting tool.
 
-- `.hspec`
+### `.hspec`
 
 Using a dedicated file to specify options for [`hspec`](https://hspec.github.io) allows passing options only to it. Using `cabal test --test-options` would pass options to all test stanzas instead.