docs: Diataxis framework refactor — navigation restructure, content gaps, tone/style pass - #408

Draft

mefellows wants to merge 34 commits into

masterfrom

diataxis-refactor

Commits on Mar 19, 2026

docs: add diataxis refactor plan

mefellows
and
claude
committed
5f649f0
refactor(nav): restructure navigation according to Diataxis framework

mefellows
and
claude
committed
ab508b6
fix(nav): add university.md to tutorials sidebar; fix Concepts activeBaseRegex

mefellows
and
claude
committed
f106094
docs: update PLAN.md with completed phase progress

mefellows
and
claude
committed
5a1b542
fix(sidebar): correct pre-existing broken Step file references in university tutorials

mefellows
and
claude
committed
8437f9b
docs: mark all phases complete in PLAN.md; add final state summary

mefellows
and
claude
committed
fe3e1e1

Commits on Mar 20, 2026

fix(sidebar): revert step IDs to Docusaurus-stripped form

mefellows
and
claude
committed
32b9597
feat(docs): fill four Diataxis content gaps

mefellows
and
claude
committed
659dee5
fix(how_pact_works): extract message pact how-to into consumer guide

mefellows
and
claude
committed
b17260c
fix(5-minute-guide): remove explanation digressions from tutorial

mefellows
and
claude
committed
308991d
fix(pact_nirvana): declare as how-to guide and reframe step 1

mefellows
and
claude
committed
e983535
fix(matching): move best practice opinions to consumer.md

mefellows
and
claude
committed
f6adb04
fix(can_i_deploy): replace explanatory opening with one-liner + link

mefellows
and
claude
committed
da76164
fix(recipes/kafka): rewrite as how-to guide with imperative voice

mefellows
and
claude
committed
2de1c2e
fix(consumer): extract Best Practice Guide to consumer/best_practices.md

mefellows
and
claude
committed
d86cead
fix(conceptual_overview): make self-contained, remove forward references

mefellows
and
claude
committed
d1ff47a
chore: update PLAN.md with completed phases and tone/style tasks

mefellows
and
claude
committed
23ea70d
style(T1): getting_started.md — remove first-person plural

mefellows
and
claude
committed
9b02794
style(T2): what_is_pact_good_for.md — remove "we" and soften imperative

mefellows
and
claude
committed
9dbfd78
style(T3): how_pact_works.md — remove filler opener, first-person plural, hedging

mefellows
and
claude
committed
93612bc
style(T5): testing-scope.md — remove filler opener, first-person plural

mefellows
and
claude
committed
58d567b
style(T6): verifying_pacts.md — remove first-person plural

mefellows
and
claude
committed
dd57ebe
style(T7): provider_states.md — remove filler opener

mefellows
and
claude
committed
59fe710
style(T8): sharing_pacts.md — remove first-person plural

mefellows
and
claude
committed
01a4a31
style(T10a): faq.md — remove first-person plural, filler openers, hedging

mefellows
and
claude
committed
66ddcf0
style(T10b): convinceme.md — remove first-person plural

mefellows
and
claude
committed
dfbfae0
style(T11): consumer pages — remove first-person plural, filler openers

mefellows
and
claude
committed
de5592e
style(T12): provider pages — remove first-person plural, fix typos

mefellows
and
claude
committed
f7e7f93
style(T13): pact_nirvana steps 3-7 — remove first-person plural throughout

mefellows
and
claude
committed
4c52bd8
style(T14): recipe pages — remove first-person voice

mefellows
and
claude
committed
41c3519
style(T15): plugins pages — remove first-person plural and informal voice

mefellows
and
claude
committed
7b19fb5
chore: mark Phase 16 complete in PLAN.md, advance Phase 17

mefellows
and
claude
committed
d4ba0fb
fix: resolve 3 of 5 pre-existing broken links (concepts.md, step_1.md)

mefellows
and
claude
committed
fc777b9
chore: finalise PLAN.md — Phase 17 complete

mefellows
and
claude
committed
cdb26ed

Navigation Menu

Uh oh!

docs: Diataxis framework refactor — navigation restructure, content gaps, tone/style pass - #408

docs: Diataxis framework refactor — navigation restructure, content gaps, tone/style pass#408
mefellows wants to merge 34 commits into
masterfrom
diataxis-refactor

Commits on Mar 19, 2026

docs: add diataxis refactor plan

refactor(nav): restructure navigation according to Diataxis framework

fix(nav): add university.md to tutorials sidebar; fix Concepts activeBaseRegex

docs: update PLAN.md with completed phase progress

fix(sidebar): correct pre-existing broken Step file references in university tutorials

docs: mark all phases complete in PLAN.md; add final state summary

Commits on Mar 20, 2026

fix(sidebar): revert step IDs to Docusaurus-stripped form

feat(docs): fill four Diataxis content gaps

fix(how_pact_works): extract message pact how-to into consumer guide

fix(5-minute-guide): remove explanation digressions from tutorial

fix(pact_nirvana): declare as how-to guide and reframe step 1

fix(matching): move best practice opinions to consumer.md

fix(can_i_deploy): replace explanatory opening with one-liner + link

fix(recipes/kafka): rewrite as how-to guide with imperative voice

fix(consumer): extract Best Practice Guide to consumer/best_practices.md

fix(conceptual_overview): make self-contained, remove forward references

chore: update PLAN.md with completed phases and tone/style tasks

style(T1): getting_started.md — remove first-person plural

style(T2): what_is_pact_good_for.md — remove "we" and soften imperative

style(T3): how_pact_works.md — remove filler opener, first-person plural, hedging

style(T5): testing-scope.md — remove filler opener, first-person plural

style(T6): verifying_pacts.md — remove first-person plural

style(T7): provider_states.md — remove filler opener

style(T8): sharing_pacts.md — remove first-person plural

style(T10a): faq.md — remove first-person plural, filler openers, hedging

style(T10b): convinceme.md — remove first-person plural

style(T11): consumer pages — remove first-person plural, filler openers

style(T12): provider pages — remove first-person plural, fix typos

style(T13): pact_nirvana steps 3-7 — remove first-person plural throughout

style(T14): recipe pages — remove first-person voice

style(T15): plugins pages — remove first-person plural and informal voice

chore: mark Phase 16 complete in PLAN.md, advance Phase 17

fix: resolve 3 of 5 pre-existing broken links (concepts.md, step_1.md)

chore: finalise PLAN.md — Phase 17 complete