Skip to content

docs: add AUDIENCES.md per audience-identification spec#23

Merged
github-actions[bot] merged 5 commits into
developfrom
docs/audience-artifact
May 20, 2026
Merged

docs: add AUDIENCES.md per audience-identification spec#23
github-actions[bot] merged 5 commits into
developfrom
docs/audience-artifact

Conversation

@nolte
Copy link
Copy Markdown
Owner

@nolte nolte commented May 19, 2026

Summary

Apply spec/project/audience-identification/ to this repository for the
first time and persist the resulting audience list at AUDIENCES.md at the
repo root (the spec's canonical default location). The artifact is the
prerequisite for the planned audience-doc-author refactor of README.md
and docs/modules/*.md, and unblocks every downstream spec that references
an audience list (readme-structure, release-notes-audience-analysis,
release-skill-layer, future SLA or threat-model specs).

Changes

  • Add AUDIENCES.md at the repository root with:
    • A written bounded context (in scope / out of scope), declared before any
      audience is listed, per spec §Requirements.
    • One audience under Direct consumers (Taskfile-consumer project,
      assumed, primary).
    • Two audiences under Operators (consumer-side developer, primary;
      consumer-side CI, secondary), both assumed.
    • Two audiences under Contributors / maintainers (module maintainer,
      primary; documentation author, secondary), both assumed.
    • Two audiences under Governing parties (nolte portfolio architecture
      conventions, primary; Renovate / dependency-pinning governance,
      secondary), both confirmed.
    • Indirect audiences explicitly recorded as none — purely developer tooling, every affected person already covered under Operators or Direct consumers.
  • Every audience entry carries label, category, surface, expects,
    track, status, criticality, and open questions, as the spec
    requires.
  • All six audiences map to developer-docs; the artifact explicitly states
    the repository has no user-docs audience and why.

Linked issues

Refs spec/project/audience-identification/

Testing

  • audience-identify skill (operation run) drove the artifact end-to-end:
    bounded context declared first, each of the five relationship categories
    surfaced separately, confirmed only set after explicit confirmation in
    the conversation.
  • Manual check against the spec's Acceptance Criteria:
    • Bounded context declared before any audience is listed.
    • All five relationship categories addressed (Indirect = none with
      reason).
    • Every entry has label, category, surface, expectation, track,
      status, open questions, criticality.
    • Every entry tagged confirmed or assumed.
    • Artifact lives at AUDIENCES.md at the bounded-context root.

Risk / rollout notes

Low risk — AUDIENCES.md is a documentation artifact with no runtime or CI
behaviour. The primary open question (concrete identity of the Taskfile
consumers) is recorded inline so the Direct-consumer entry can be promoted
from assumed to confirmed later without rewriting the file.

Two assumed clusters are worth surfacing for follow-up:

  • Consumer identity is unknown today; until at least one downstream repo
    cites this collection by name, Direct consumers stays assumed.
  • Operator / contributor audiences are author-inferred from CLAUDE.md and
    the repo's PR history; a one-paragraph note from any real maintainer
    besides the repo owner would let those flip to confirmed.

nolte and others added 2 commits May 19, 2026 22:17
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>
nolte and others added 3 commits May 20, 2026 12:44
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>
@nolte nolte marked this pull request as ready for review May 20, 2026 16:08
@nolte nolte added the automerge Allow automatic Merge. label May 20, 2026
@github-actions github-actions Bot merged commit 2a40edf into develop May 20, 2026
8 checks passed
@github-actions github-actions Bot deleted the docs/audience-artifact branch May 20, 2026 16:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automerge Allow automatic Merge. chore Maintenance documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant