preferences-documentation

name	preferences-documentation
description	Documentation conventions including structure, formatting, and maintenance practices. Load when writing or reviewing documentation.

Documentation

References

1. Méndez Fernández, D., Penzenstadler, B.: Artefact-based requirements engineering: The AMDiRE approach. Requir. Eng. 20, 405–434 (2015). https://arxiv.org/abs/1611.10024
2. Chuprina, T., Mendez, D., Wnuk, K.: Towards artefact-based requirements engineering for data-centric systems. arXiv [cs.SE]. (2021)
3. ISO/IEC/IEEE international standard - systems and software engineering – life cycle processes – requirements engineering, (2018)
4. IEEE standard for information technology–systems design–software design descriptions, (2009)
5. Diátaxis: A systematic approach to technical documentation authoring. https://diataxis.fr.

Location

• Most repositories use docs/ for their active documentation but some have both docs/ and another directory like site/, website/, nbs/, etc.
• Most README.md files in the repository root should aim to include minimal content with relevant links to the docs website unless they do not yet have docs.

Structure

Generally assume we intend to follow this standard structure for repository documentation combining user-facing and development documentation:

docs/
├── tutorials/           # Diataxis: Learning-oriented lessons
├── guides/              # Diataxis: Task-oriented how-tos
├── concepts/            # Diataxis: Understanding-oriented explanations
├── reference/           # Diataxis: Information-oriented API docs (optional)
├── about/               # Contributing, conduct, links into development
├── development/         # Development documentation (adapted AMDiRE-based)
│   ├── index.md         # Development overview and navigation
│   ├── context/         # Context Specification (problem domain)
│   │   ├── index.md     # Context overview and table of contents
│   │   └── context.md   # Problem domain, stakeholders, objectives
│   ├── requirements/    # Requirements Specification (problem ↔ solution bridge)
│   │   ├── index.md     # Requirements overview and traceability matrix
│   │   └── requirements.md  # Functional/non-functional requirements
│   ├── architecture/    # System Specification (solution space)
│   │   ├── index.md     # Architecture overview and table of contents
│   │   └── architecture.md  # System design and component structure
│   ├── traceability/    # Requirements traceability
│   │   ├── index.md     # Traceability overview
│   │   └── testing.md   # Test framework and validation approach
│   └── work-items/      # Work packages and implementation tracking
│       ├── index.md     # Work items overview and status dashboard
│       ├── active/      # In-progress work items
│       ├── completed/   # Finished items with PR/ADR/RFC/RFD references
│       └── backlog/     # Planned but not yet started items
└── notes/               # EPHEMERAL: Working notes excluded from rendering
    └── [category]/      # Temporary staging (see "Working notes" section)

Document evolution

Many projects will begin with only docs/development/ and add the user docs directories later. Initial development drafts context.md, requirements.md, architecture.md, and testing.md as single comprehensive documents. As complexity grows—expected for most real projects—decompose each document by major subsection into separate files with descriptive names (e.g., context.md → stakeholders.md, objectives.md, constraints.md). Update the corresponding index.md to serve as table of contents and navigation after sharding. This pattern maintains manageability while preserving traceability as documentation scales. If the documentation becomes sufficiently complex, we can continue to refactor into a directory tree with additional levels.

Working notes

The docs/notes/ directory serves as ephemeral staging for development notes that have not been formalized into the permanent documentation structure. These notes are explicitly temporary and must be either migrated to formal documentation or discarded.

Organization: Use category-based subdirectories with kebab-case filenames:

docs/notes/
├── security/           # Security investigations
├── architecture/       # Architectural exploration
├── performance/        # Performance analysis
└── [category]/         # Other categorized notes

Exclusion from rendering: Working notes must never appear in rendered documentation sites. Configure your documentation system accordingly:

• Astro (content collections): Only include specific directories in src/content/config.ts, implicitly excluding notes/
• Quarto (_quarto.yml):

  project:
    render:
      - "!docs/notes/**"
  

• Docusaurus (docusaurus.config.js):

  docs: {
    exclude: ['**/notes/**']
  }
  

• MkDocs (mkdocs.yml):

  exclude_docs: |
    notes/
  

Lifecycle: Every working note must eventually follow one of two paths:

1. Migrate to formal documentation: Extract valuable insights, revoice from informal working notes to formal documentation style, and move content to the appropriate location in the user-facing docs (tutorials/, guides/, concepts/, reference/) or development docs (development/context/, development/requirements/, development/architecture/, etc.). Delete the working note after migration.

2. Discard when no longer relevant: Delete notes that served temporary investigation purposes, documented abandoned approaches, or have been superseded by other documentation.

Working notes should not persist indefinitely. Regularly audit docs/notes/ for stale content and progress notes through their lifecycle. The goal is to keep this directory empty or minimal in stable projects.

Relationship to work items: Unlike docs/development/work-items/ which maintains a permanent record of development efforts with traceability to issues and PRs, working notes in docs/notes/ are ephemeral drafts that get cleaned up after their content is either formalized or determined to be no longer needed.

Markdown formatting conventions

Some documentation generators like Astro Starlight require markdown files to use YAML frontmatter with a title like

---
title: "Title: subtitle"
---

instead of the # Title: subtitle format. As such it's best to primarily use this convention when authoring markdown. Note that quotes are required in YAML when the title contains special characters like colons; simple titles without special characters don't require quotes. Not all markdown documents require subtitles—the subtitle format is shown here for completeness to demonstrate proper quoting.

Plain markdown systems (GitHub, static markdown) also support frontmatter titles, making this convention broadly compatible. When working in a documentation directory, check for frontmatter in existing files to confirm the convention in use. If files contain title: in YAML frontmatter, use ## to start content sections to avoid duplicate titles in rendered output.

Consecutive **Term**: description lines merge into one paragraph when rendered. Use - **Term**: description bullet format for 2+ definitions.

Key principles

• Separate user documentation (diataxis framework) from development documentation (AMDiRE methodology)
• User docs focus on helping users learn, accomplish tasks, understand concepts, and find reference information
• Development docs provide traceability: context (why) → requirements (what) → architecture (how) → work items (implementation)
• Work items bridge planning to execution with workflow state tracking (backlog → active → completed)
• Maintain bidirectional traceability between requirements, architecture decisions, and implementation artifacts
• Reference GitHub issues, pull requests, ADRs, RFCs, or RFDs in completed work items for full audit trail
• Name files in the work-items directory using the pattern <issue-id>-<very-short-description>.md with zero-padded issue IDs to support up to four digits (e.g. GitHub issue #12 becomes 0012-description.md in work-items).

Architecture decision records

ADRs live in docs/development/architecture/adrs/ following the AMDiRE structure above. Authoring conventions covering section structure, status lifecycle, commanding voice, business justification requirements, and antipatterns are in references/adr-conventions.md. Load that companion file when writing, reviewing, or evaluating ADRs.

Temporal provenance

Documents carry temporal context that informs their reliability. Use the following frontmatter fields to make provenance explicit.

Provenance frontmatter fields

These fields are optional but recommended for any document in docs/ that persists beyond a single session.

• created: YYYY-MM-DD — date the document was first authored.
• last-validated: YYYY-MM-DD — date the document's content was last reviewed and confirmed accurate, independent of incidental edits (typo fixes, formatting). Session-checkpoint updates this field for documents reviewed during a session. Session-orient uses it for staleness scanning: a file modified recently for formatting but last validated months ago is stale; an unmodified file validated recently is not.
• superseded-by: <path or description> — marks a document as replaced by another. Documents with this field older than 30 days should be deleted or archived during session-orient health checks.

Conflict detection and resolution

No rigid precedence hierarchy exists between document types. A recently edited working note can supersede an older formal spec, and vice versa. When information from different documents contradicts, recency of the specific conflicting content is the primary signal.

Use git history rather than filesystem modification times to assess recency. Filesystem mtime is unreliable — it changes on git checkout, git rebase, and other operations that do not represent content edits. Prefer git log --follow -1 --format='%ai' -- <file> for file-level provenance and git blame -L <range> <file> for line-level provenance.

When contradictions are detected during any task, flag them to the user with provenance evidence (file paths, dates, relevant line ranges) rather than silently preferring one source. The user decides which source is authoritative; the agent's role is to surface the contradiction and the temporal evidence.

docs/notes/ index

Maintain a docs/notes/README.md file as a table of contents for the ephemeral notes directory. Each entry should include the subdirectory or file name, a one-line description of its purpose, and the date it was created or last validated. This index helps agents and humans quickly assess which notes exist and their approximate currency without reading each file. Update the index when creating, deleting, or significantly revising working notes.

Code

• In code, prefer docstrings relevant to a given programming language over code comments as the docstrings end up in docs/reference/ files automatically generated by most language API reference documentation tools.
• For whether an inline comment should exist at all, and for when to remove existing comments, follow the Code comments policy in preferences-style-and-conventions: reserve inline comments for what the code cannot express and remove those that merely restate it.

Maintenance

• When making code changes, immediately identify all affected documentation artifacts with surgical precision:
  • docs/development/context/ if problem domain or stakeholders change
  • docs/development/requirements/ if functional/non-functional requirements change
  • docs/development/architecture/ if design decisions, components, or technology change
  • docs/development/traceability/ if test strategy or validation approach changes
  • docs/development/work-items/ for implementation status tracking
  • Repository README.md and user-facing docs/ if behavior changes
• Update affected documentation immediately in the same session, not at an undetermined future point.
• Commit documentation updates atomically in series with the related code changes, following the same proactive atomic commit workflow specified in ~/.claude/skills/preferences-git-version-control/SKILL.md.
• Be judicious in the use of documentation, ensuring that it is clear, concise, and accurate for humans to read and understand.
• Proactively remove, refactor, and consolidate documentation as relevant to maintain optimal correspondence between the code and documentation.