Update README.md

Author: synalice

README.md

@@ -1,38 +1,52 @@
 # perfect-helloworld
 
-A reference-grade C helloworld project.
+A _(deliberately over-engineered)_ reference-grade C "Hello World" project.
 
-Prints "Hello, World!" with maximal engineering discipline!
+This is what a modern, best practice-oriented C project might look like in 2026.
+The project is aimed at developers looking for a opinionated and modern starting
+point.
+
+Feedback and constructive criticism are welcomed!
+
+## Non-goals
+
+- Being the smallest or simplest C "Hello World" example
+- Avoiding modern tooling for portability
 
 ## Features
 
-- Meson build system;
-- Cross-compilation support;
-- Nix flake for dependency management;
-- MIT license;
-- GitHub Actions CI;
-- Standard project structure (`docs/`, `include/`, `src/`, `tests/`, `scripts/`);
-- Supports `llvm-vs-code-extensions.vscode-clangd` instead of `ms-vscode.cpptools`;
-- Doxygen support;
-- Pkg-config (generates `.pc` file);
-- Unit testing support via [Unity] testing framework;
-- Pre-commit hooks:
-  - `clang-format`
-  - `clang-tidy`
-  - `meson format`
-  - `nix flake check`
-  - `nix fmt`
-  - [IWYU]
-  - [cppcheck]
-  - [REUSE]
-  - Formatting JSON files with [jq];
+- Meson build system
+- Cross-compilation support
+- Nix flake for dependency management
+- MIT license
+- GitHub Actions CI
+- Standard project structure (`docs/`, `include/`, `src/`, `tests/`, `scripts/`)
+- Uses `llvm-vs-code-extensions.vscode-clangd` instead of `ms-vscode.cpptools`
+- Doxygen support
+- Pkg-config (generates `.pc` file)
+- Unit testing support via [Unity] testing framework
+
+### Pre-commit hooks
+
+The following checks are enforced via [prek] (a lightweight alternative to
+[pre-commit]):
+
+- `clang-format`
+- `clang-tidy`
+- `meson format`
+- `nix flake check`
+- `nix fmt`
+- [IWYU]
+- [cppcheck]
+- [REUSE]
+- [jq] (for JSON formatting)
 
 ## Getting started
 
-To setup your environment for developing this project run these commands:
+To set up your development environment, run the following commands:
 
 1. Install [Nix] and [direnv].
-1. Clone and cd into the repository.
+1. Clone the repository and cd into the project directory.
 
     ```bash
     git clone https://github.com/synalice/perfect-helloworld
@@ -74,16 +88,21 @@ To cross-compile the project, run this script:
 ```
 
 > [!WARNING]\
-> Invoking it for the first time make take some time, because Nix will download or
+> Invoking it for the first time may take some time, because Nix will download or
 > build some parts of the cross toolchain.
 
 > [!TIP]\
-> To cross-compile for different host architectures replace
+> To cross-compile for different host architectures, replace
 > `aarch64-multiplatform` with `riscv64` or something else. [Read more
 > here](https://nix.dev/tutorials/cross-compilation.html#choosing-the-host-platform-with-nix).
 
 > [!TIP]\
-> To build dev or doc derivation (package) replace `out` with `dev` or `doc`.
+> To build the `dev` or `doc` derivation, replace `out` with `dev` or `doc`.
+
+## Known issues
+
+- No cross-compilation in CI, as downloading cross toolchains from Nix binary
+  caches significantly increases CI time.
 
 ## License
 
@@ -92,8 +111,10 @@ This project is under the [MIT] license.
 [jq]: https://jqlang.org/
 [Nix]: https://nixos.org/download
 [MIT]: https://opensource.org/license/mit
+[prek]: https://github.com/j178/prek
 [IWYU]: https://include-what-you-use.org/
 [Unity]: https://www.throwtheswitch.org/unity
 [REUSE]: https://reuse.software/
 [direnv]: https://direnv.net/#getting-started
 [cppcheck]: https://en.wikipedia.org/wiki/Cppcheck
+[pre-commit]: https://pre-commit.com/