docs: add AUDIENCES.md per audience-identification spec#23
Merged
Conversation
Apply spec/project/audience-identification/ to this repository for the first time and persist the result at AUDIENCES.md at the repo root (the spec's canonical default location). Findings summary: - Bounded context: reusable Taskfile include modules consumed via remote-taskfiles; product is the YAML files themselves. - Direct consumers: Taskfile-consumer project (assumed, primary). - Operators: consumer-side developer (primary) and consumer-side CI (secondary), both assumed. - Contributors / maintainers: module maintainer (primary) and documentation author (secondary), both assumed. - Governing parties: nolte portfolio architecture conventions (confirmed, primary) and Renovate / dependency-pinning governance (confirmed, secondary). - Indirect audiences: none — purely developer tooling with no end-user surface behind it. All six audiences map to the developer-docs track; the repository explicitly serves no user-docs audience. This artifact unblocks downstream specs that reference an audience list (readme-structure, release-notes-audience-analysis, release-skill-layer, future SLA or threat-model specs) and is the prerequisite for the planned audience-doc-author refactor of README.md and docs/modules/*.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Apply the audience artefact added in this PR to the rendered docs. The six developer-docs audiences cluster into three needs: - Adoption (Direct-consumer + both Operator audiences): README intro + Usage stay the include-markdown integration point; per-module pages keep the Tasks / Variables / Example schema and grow two audience-driven sections (Prerequisites for the local-developer operator, Troubleshooting for both operator surfaces). - Contribution (both Contributor audiences): docs/contributing.md is new and becomes the canonical entry point for the contributor track in the rendered site. CLAUDE.md stays as the source of truth for AI-assisted module work; the new page points there and expands on documentation-author concerns (marker contract, module-page schema, Vale vocabulary). - Governance (both Governing audiences, both confirmed): docs/governance.md is new and consolidates portfolio-spec conformance, reusable-workflow pin discipline, Probot settings, Vale stack, and Renovate setup. mkdocs.yml gains two top-level nav entries (Contributing, Governance) without disturbing the existing modules tree. The README intro / usage marker pair is preserved exactly as before: adoption-cluster content stays inside the markers and flows into docs/index.md via mkdocs-include-markdown-plugin; contribution and governance content stays outside the markers and is reachable from the README via short pointers. The local Vale vocabulary gains six purely technical terms (venv, venvs, automerge, namespace, repo, config) that the refactored prose uses consistently with CLAUDE.md and AUDIENCES.md. Vale before refactor: 0 errors, 14 suggestions. Vale after refactor: 0 errors, 5 suggestions (all Microsoft.ComplexWords / Semicolon / Vocab style hints on technically correct terms; no Microsoft.Passive regressions). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reorganise the rendered docs by audience and Diátaxis quadrant, ship a
German translation alongside the English source, and tighten the
content of every page.
Structural changes:
- The mkdocs site now serves two language tracks via
mkdocs-static-i18n (en default, de) under parallel docs/en/ and
docs/de/ folders.
- Each track follows the Diátaxis quadrants: Home (orientation),
Getting Started (tutorial), Guides (how-to), References (reference +
explanation). The previous flat docs/{index,contributing,governance}.md
and docs/modules/*.md files are removed; their content lives in the
new structure.
Content changes (EN, treated as source):
- Home: only the README intro snippet plus a three-cluster audience
map; usage / pin / override details moved out.
- Getting Started: real tutorial that ends on a working
`task pre-commit:start`, with an explicit pin-to-tag step.
- References gains a "Common contract" section documenting the
USER_WORKING_DIR invariant, pin strategy, long-form override syntax,
and venv contract. Module pages link to it instead of repeating
themselves.
- Module pages keep the Prerequisites / Tasks / Variables / Example /
Troubleshooting schema and gain audience-driven troubleshooting
cases (wrong cluster, port collision, hook cache, helm repo address
drift).
DE track:
- All ten DE pages are real German translations, not English skeletons.
Intra-track anchor links target the German heading slugs.
Linter and build setup:
- .vale.ini: disable Microsoft, Vale.Spelling, and Vale.Terms for
docs/de/**/*.md so German prose doesn't trip English-only checks.
Microsoft.Ranges / Microsoft.RangeFormat stay off globally because
they fire on YAML dates and version pins.
- Local Vale vocabulary gains `kubeconfig`.
- requirements-dev.txt pins mkdocs-static-i18n.
- README module table: switch ./src/... links to absolute GitHub URLs
so mkdocs --strict resolves them when the intro snippet is included
into the rendered home page.
Verification (local):
- vale docs/: 0 errors, 0 warnings, 19 suggestions (Microsoft style
hints on technically correct terms).
- mkdocs build --strict: clean for both en and de, no anchor warnings.
- pre-commit run --all-files: all hooks pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Resolve the eleven Microsoft + Vale ERROR-severity findings that failed the spelling check on PR #23: unspace em-dashes between bold labels and emphasis, replace "does not" / "cannot" with contractions, swap "e.g." for "for example", and singularise "Taskfiles" out-of-scope item. Add the org name "nolte" to the local Vale vocabulary so Vale.Spelling accepts it at sentence-internal positions too. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Vale-CI fails on any annotation on diff-added lines, not just on ERROR-severity ones. Resolve the remaining Microsoft.Passive, Microsoft.Vocab (against / above / author / broadly), Microsoft.Semicolon, Microsoft.GeneralURL (URL), Microsoft.Hyphens, Microsoft.Headings, Microsoft.Acronyms, and Microsoft.We findings across AUDIENCES.md and the docs/en/ pages touched in this branch by rewording to active voice, splitting semicolons into periods, swapping flagged vocabulary, and spelling out SLA. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Apply
spec/project/audience-identification/to this repository for thefirst time and persist the resulting audience list at
AUDIENCES.mdat therepo root (the spec's canonical default location). The artifact is the
prerequisite for the planned
audience-doc-authorrefactor ofREADME.mdand
docs/modules/*.md, and unblocks every downstream spec that referencesan audience list (readme-structure, release-notes-audience-analysis,
release-skill-layer, future SLA or threat-model specs).
Changes
AUDIENCES.mdat the repository root with:audience is listed, per spec §Requirements.
assumed, primary).consumer-side CI, secondary), both
assumed.primary; documentation author, secondary), both
assumed.conventions, primary; Renovate / dependency-pinning governance,
secondary), both
confirmed.none — purely developer tooling, every affected person already covered under Operators or Direct consumers.label,category,surface,expects,track,status,criticality, andopen questions, as the specrequires.
developer-docs; the artifact explicitly statesthe repository has no
user-docsaudience and why.Linked issues
Refs
spec/project/audience-identification/Testing
audience-identifyskill (operationrun) drove the artifact end-to-end:bounded context declared first, each of the five relationship categories
surfaced separately,
confirmedonly set after explicit confirmation inthe conversation.
nonewithreason).
status, open questions, criticality.
confirmedorassumed.AUDIENCES.mdat the bounded-context root.Risk / rollout notes
Low risk —
AUDIENCES.mdis a documentation artifact with no runtime or CIbehaviour. The primary open question (concrete identity of the Taskfile
consumers) is recorded inline so the Direct-consumer entry can be promoted
from
assumedtoconfirmedlater without rewriting the file.Two
assumedclusters are worth surfacing for follow-up:cites this collection by name, Direct consumers stays
assumed.CLAUDE.mdandthe repo's PR history; a one-paragraph note from any real maintainer
besides the repo owner would let those flip to
confirmed.