Restructure tutorial

.github/workflows/ci.yml

@@ -63,7 +63,7 @@ jobs:
           GIT_COMMITTER_NAME: ${{ github.actor }}
           GIT_COMMITTER_EMAIL: ${{ github.actor }}@users.noreply.github.com
         run: |
-          git add -f doc/tutorial
+          git add -f doc/tutorial doc/how_to doc/reference
           git add Readme.md
           git commit -m "Generate cljdoc docs for ${GITHUB_REF_NAME}"
 

.gitignore

@@ -4,5 +4,7 @@
 /target
 /pom.xml
 /doc/tutorial/
+/doc/how_to/
+#/doc/_*.md
 .clj-kondo/
 .lsp/

CLAUDE.md

@@ -15,9 +15,17 @@ Docs are published on cljdoc.org. Source articles live in `doc/`:
 
 - `doc/cljdoc.edn` — navigation tree (`{:cljdoc.doc/tree ...}`).
 - `doc/integrant.md`, `doc/example.md` — checked-in articles.
-- `doc/tutorial/*.md` — **generated** from `test/darkleaf/di/tutorial/*.clj`
-  by `script/tutorial-to-md.sh`. Path is in `.gitignore`; the files only
-  exist in CI-built release commits, never on `master`.
+- `doc/tutorial/*.md` and `doc/how_to/*.md` — **generated** from the
+  matching `test/darkleaf/di/{tutorial,how_to}/*.clj` files by
+  `script/tutorial-to-md.sh`. Paths are gitignored; the files only
+  exist in CI-built release commits.
+- `doc/reference/*.md` — **plain tracked markdown**, not generated.
+  Reference pages are descriptive prose; verified examples for
+  whatever the page describes live in regular tests
+  (e.g. `dependency_types_test.clj` for the Factory protocol page).
+- Planning artifacts from the v6 docs restructure live in
+  `doc/_journey.md` (chapter-by-chapter audit) and
+  `doc/_structure.md` (final TOC + rationale).
 
 ### Release flow
 
@@ -72,11 +80,98 @@ Then trigger a rebuild on `https://cljdoc.org/d/org.clojars.darkleaf/di/X.Y.Z`.
 
 cljdoc rewrites markdown links between articles. Use either:
 
-- relative to the source file: `tutorial/a_intro_test.md` (from `doc/example.md`)
-- root-relative: `/doc/tutorial/a_intro_test.md`
+- relative to the source file: `tutorial/a_your_first_system_test.md` (from `doc/example.md`)
+- root-relative: `/doc/tutorial/a_your_first_system_test.md`
 
-A bare `doc/tutorial/a_intro_test.md` (no leading slash) is **not**
-recognised and renders as a broken external link.
+A bare `doc/tutorial/a_your_first_system_test.md` (no leading slash)
+is **not** recognised and renders as a broken external link.
+
+For an article-to-API-var link, use the full cljdoc URL with the
+`CURRENT` placeholder — cljdoc rewrites `CURRENT` to the version
+the reader is viewing:
+
+```
+[`di/->memoize`](https://cljdoc.org/d/org.clojars.darkleaf/di/CURRENT/api/darkleaf.di.core#->memoize)
+```
+
+Wikilinks (`[[ns/var]]`) only work inside docstrings, not in
+articles.
+
+## Documentation conventions
+
+Settled during the v6 restructure. See `doc/_structure.md` for the
+chapter-by-chapter rationale.
+
+### Audience
+
+- Primary: a Clojure developer familiar with Integrant or Component.
+- Secondary: a Clojure developer who has never used a DI framework.
+  Don't assume Integrant knowledge in chapter bodies.
+- Many readers are non-native English speakers. Optimise prose
+  for them: short sentences, no English `;` in prose (use
+  periods), no obscure idioms (`slip past it` is the kind that
+  trips people up; everyday phrasing like *side effect* or
+  *before any traffic* is fine).
+
+### Voice
+
+- Matter-of-fact, declarative. Match `doc/integrant.md` and
+  Stuart Sierra's *Reloaded Workflow* tone. No marketing language.
+- No comparisons to other DI libraries inside tutorial or how-to
+  chapters. The Integrant comparison lives in `doc/integrant.md`
+  on its own.
+
+### Terminology
+
+- **Do not use the word "middleware"** in tutorial or how-to
+  chapters. Refer readers to `doc/reference/middleware_types.md`
+  when the concept is unavoidable. Talk about "arguments to
+  `di/start`" instead.
+- **Math-style names** (`a`, `b`, `c`, …) are the project's
+  authorial style. Keep them — don't substitute concrete names
+  without a reason.
+- **Keyword vs symbol** is about *intent*, not swap-ability. Both
+  can be substituted via the registry. A keyword means the author
+  decided to abstract the dependency (most commonly inside a
+  library or reusable internal module). A symbol points at a
+  specific var.
+
+### Directory layout
+
+- Tutorial chapters: `test/darkleaf/di/tutorial/[a-l]_<slug>_test.clj`.
+  Letter prefix `a..l` matches chapter order (1–12) alphabetically.
+- How-to recipes: `test/darkleaf/di/how_to/<slug>_test.clj`. No
+  order prefix.
+- Reference pages: `doc/reference/<slug>.md` — plain markdown,
+  tracked.
+- When adding a new doc subdirectory, also update
+  `script/tutorial-to-md.sh` (it iterates `tutorial`, `how_to`,
+  `reference`) and the `git add -f` line in
+  `.github/workflows/ci.yml` release job.
+
+### Test idioms in chapter files
+
+These conventions apply to tutorial and how-to chapter `.clj`
+files. Regular tests under `test/darkleaf/di/*_test.clj` should
+stay strict — prefer object-identity comparison there so subtle
+regressions don't slip through.
+
+- Use `darkleaf.di.utils/catch-some` plus `ex-message` / `ex-data`
+  for exception assertions. Compare messages and structured data,
+  not exception objects by identity.
+- Inline `(ex-info "..." {})` constructions where they fire — do
+  not pass exceptions through the registry just to assert on
+  them later.
+- Add `;; ...` comments above non-obvious assertions to explain
+  what they verify.
+
+### Reference pages
+
+- A Reference page earns its keep when it adds material the
+  docstring does not: decision-trees, walks through code-level
+  patterns, design history, pitfall lists, aggregations across
+  multiple sources.
+- Avoid duplicating the docstring 1-for-1.
 
 ## Release/build gotchas (not cljdoc-specific but related)