📝 Check off the docs restructure and note it in the changelog

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- restructure the documentation: README.md for users, CONTRIBUTING.md for contributors, and development/ for the decisions, rejected alternatives and known issues
+- document the decisions and known issues for CI, tooling, testing, publishing and the workflow
+
 ## [0.1.5] - 2026-09-15
 
 - improve CI configuration

backlog.tasks

@@ -24,32 +24,32 @@ Bugs:
 Enhancements:
 
 Documentation:
-☐ Clean up CONTRIBUTING.md and README.md, create docs
-    ☐ Review existing documentation for accuracy and completeness
-    ☐ README.md should be the main entry point for users, and CONTRIBUTING.md should be the main entry point for contributors
-    ☐ Move the decisions, shortcomings and known issues out of README.md and CONTRIBUTING.md
-        ☐ Decided: category files under development/ (one per area), not ADRs. Each decision is a block with #### Decision (YYYY-MM) / #### Why / #### Rejected / #### Known issue; rationale in development/README.md
-        ☐ have a look at other well known repositories for inspiration on how to structure the docs
-        ☐ often times a docs folder is used, but this usually contains further user of the library documentation, that is deployed to a website. Deployment is out of scope for now
-        ☐ make sure to preserve that information in the new docs
-        ☐ development/README.md - index and decision-block convention
-        ☐ development/workflow.md - branching, script prefixes, feedback tiers, commits
-        ☐ development/tooling.md - toolchain decisions and editor setup
-        ☐ development/testing.md - type-driven testing
-        ☐ development/ci.md - pipeline, runner image, coverage serving
-        ☐ development/publishing.md - release and npm publishing
-        ☐ development/library.md - public API design and its limitations
-    ☐ README.md
-        ☐ I really like the order perl documentation does it: name with a single line description, version, Synopsis, Description, examples, API reference, license
+✔ Clean up CONTRIBUTING.md and README.md, create docs @done
+    ✔ Review existing documentation for accuracy and completeness @done
+    ✔ README.md should be the main entry point for users, and CONTRIBUTING.md should be the main entry point for contributors @done
+    ✔ Move the decisions, shortcomings and known issues out of README.md and CONTRIBUTING.md @done
+        ✔ Decided: category files under development/ (one per area), not ADRs. Each decision is a block with #### Decision (YYYY-MM) / #### Why / #### Rejected / #### Known issue; rationale in development/README.md @done
+        ✔ have a look at other well known repositories for inspiration on how to structure the docs @done
+        ✔ often times a docs folder is used, but this usually contains further user of the library documentation, that is deployed to a website. Deployment is out of scope for now @done
+        ✔ make sure to preserve that information in the new docs @done
+        ✔ development/README.md - index and decision-block convention @done
+        ✔ development/workflow.md - branching, script prefixes, feedback tiers, commits @done
+        ✔ development/tooling.md - toolchain decisions and editor setup @done
+        ✔ development/testing.md - type-driven testing @done
+        ✔ development/ci.md - pipeline, runner image, coverage serving @done
+        ✔ development/publishing.md - release and npm publishing @done
+        ✔ development/library.md - public API design and its limitations @done
+    ✔ README.md @done
+        ✔ I really like the order perl documentation does it: name with a single line description, version, Synopsis, Description, examples, API reference, license @done
             (example: https://metacpan.org/pod/Scalar::Util)
-        ☐ should include a clear description of the library, its purpose, and how to use it
-        ☐ Add usage examples to README.md
-        ☐ version needs to be kept in sync with package.json in release.sh
-        ☐ Not every section in current README fits in the above order, so put them in another file
-    ☐ CONTRIBUTING.md
-        ☐ should include instructions for how to contribute to the project, including how to set up a development environment, run tests, and submit pull requests
-        ☐ should include guidelines for code style and formatting and a hint, that vscode extensions are suggested from .vscode/extensions.json
-        ☐ Not every section in current CONTRIBUTING.md fits in, so put them in another file
+        ✔ should include a clear description of the library, its purpose, and how to use it @done
+        ✔ Add usage examples to README.md @done
+        ✔ version needs to be kept in sync with package.json in release.sh @done
+        ✔ Not every section in current README fits in the above order, so put them in another file @done
+    ✔ CONTRIBUTING.md @done
+        ✔ should include instructions for how to contribute to the project, including how to set up a development environment, run tests, and submit pull requests @done
+        ✔ should include guidelines for code style and formatting and a hint, that vscode extensions are suggested from .vscode/extensions.json @done
+        ✔ Not every section in current CONTRIBUTING.md fits in, so put them in another file @done