Skip to content

[codex] add Diataxis guidance to agents#192

Merged
odyslam merged 1 commit into
mainfrom
codex/diataxis-guidance
Mar 27, 2026
Merged

[codex] add Diataxis guidance to agents#192
odyslam merged 1 commit into
mainfrom
codex/diataxis-guidance

Conversation

@odyslam
Copy link
Copy Markdown
Contributor

@odyslam odyslam commented Mar 27, 2026

Summary

Adds repo-specific Diataxis guidance to AGENTS.md so documentation work in this repo has explicit rules for:

  • classifying pages by Diataxis type
  • editing incrementally instead of forcing top-down reorganization
  • organizing pages, titles, openings, and landing pages by doc type
  • using the right language and voice for tutorials, how-to guides, reference, and explanation
  • reviewing pages for mixed-mode blur and reader flow

Why

The docs are built with Diataxis, but the local agent guidance only covered Mintlify and general writing constraints. This change makes the Diataxis expectations operational for future doc edits in this repo.

Impact

  • Improves consistency of future documentation changes
  • Reduces the chance of mixed tutorial/how-to/reference/explanation pages
  • Gives agents a clearer standard for navigation and landing-page organization

Validation

  • Reviewed the upstream Diataxis source material and translated the relevant authoring rules into repo guidance
  • No automated checks were applicable for this AGENTS.md policy-only change

@odyslam odyslam marked this pull request as ready for review March 27, 2026 23:50
@odyslam odyslam merged commit e939504 into main Mar 27, 2026
2 checks passed
@odyslam odyslam deleted the codex/diataxis-guidance branch March 27, 2026 23:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant