docs: Diataxis framework refactor — navigation restructure, content gaps, tone/style pass by mefellows · Pull Request #408 · pact-foundation/docs.pact.io

mefellows · 2026-03-20T05:32:46Z

Summary

A comprehensive restructure of docs.pact.io based on the Diátaxis framework, improving content discoverability, consistency, and quality across all in-scope documentation.

Scope: All documentation except implementation_guides/, pact_broker/, and blog/ (excluded by design).

What changed

Navigation restructure (Phases 1–13)

Added Concepts sidebar (extracted from Getting Started)
Added Tutorials sidebar (replacing University nav item)
Renamed Guides → How-to Guides in nav + footer
Slimmed Getting Started; added Diátaxis signposting table to landing page
Added /university → /tutorials redirect
Fixed pre-existing broken Step file references in tutorials sidebar

Content gaps filled (Phase 14)

getting_started/why-pact.md — new Explanation: design philosophy (consumer-driven contracts, trade-offs)
getting_started/pact-file-format.md — new Reference: pact JSON schema across V1–V4
provider/best_practices.md — new How-to guide mirroring consumer.md depth
plugins/concepts.md — new Explanation: plugin model and system actors

Structural fixes (Phase 15)

Extracted Message Pact how-to walkthrough from how_pact_works.md → consumer/how_to_test_async_messages.md
Removed explanation digressions from 5-minute-getting-started-guide.md
Declared pact_nirvana.md as a how-to guide; reframed step_1.md
Moved Best Practice section from matching.md to consumer.md
Replaced Matrix explanation in can_i_deploy.md with 2-sentence summary + link
Rewrote recipes/kafka.md with imperative headings and goal-first framing
Extracted 530-line Best Practice Guide from consumer.md → consumer/best_practices.md
Made conceptual_overview.md self-contained; replaced forward references with direct links

Tone and style pass (Phase 16, T1–T15)

Removed first-person plural ("we/our") throughout 30+ pages
Removed filler openers ("Remember that...", "Keep in mind that...")
Removed hedging language ("it can be tempting to...", "you would hopefully have read")
Removed first-person author voice ("I've written...", "Let's walk through...")
Applied second-person voice consistently ("you", not "we")

Bug fixes

Fixed 3 of 5 pre-existing broken links (concepts.md, step_1.md)
The 2 remaining broken links are in implementation_guides/ (protected scope, pre-existing)

Test plan

npm run build passes with no new broken links (2 pre-existing broken links in implementation_guides/ remain)
All new pages wired into sidebars.json
All redirects added to netlify.toml for URL changes
No modifications to implementation_guides/, pact_broker/, or blog/

🤖 Generated with Claude Code

Comprehensive audit of existing docs.pact.io structure, content categorisation against the Diataxis framework (tutorials, how-to guides, explanations, reference), issues identified, and a phased implementation plan. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- Add Concepts sidebar: extracts Pact Concepts from Getting Started into its own dedicated section (terminology, matching, provider states, etc.) - Add Tutorials sidebar: replaces University nav item, promotes 5-minute guide and external workshops alongside the multi-step University content - Rename Guides -> How-to Guides in navbar and footer for clarity - Slim Getting Started to intro + How Pact Works + Should I use Pact? + FAQ - Add signposting table to landing page pointing to all 4 Diataxis quadrants - Add /university -> /tutorials redirect in netlify.toml File paths are unchanged; only sidebar membership and nav labels are updated. All existing URLs remain valid. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…BaseRegex - university.md was orphaned from all sidebars after renaming university->tutorials; add it back so /university shows proper sidebar context (netlify redirect handles external links) - Fix Concepts navbar activeBaseRegex to highlight correctly when browsing pages under /getting_started/conceptual_overview, /terminology, etc. - Tighten Getting Started regex to avoid overlap with Concepts paths Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…versity tutorials The original university sidebar referenced university/introduction/Step1..Step13 and university/message-pact-async/Step1..Step4, but the actual files are named 01_Step1..13_Step13 and 01_Step1..04_Step4 (with numeric prefixes). This was a pre-existing bug now surfaced and fixed. Also: - Convert guides sidebar from shorthand object to explicit array format - Move further_reading from Concepts/Reference to Resources sidebar (better fit: talks, articles, getting help — not technical reference) - Remove further_reading from concepts.md index table Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Docusaurus strips numeric prefixes at runtime, so 01_Step1.md has doc ID 'Step1', not '01_Step1'. Revert sidebar references back to Step1..Step13 and Step1..Step4. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

- concepts/why-pact: design philosophy explanation (consumer-driven contracts, generated pact files, broker model, trade-offs) - concepts/pact-file-format: Reference page for pact JSON schema across spec versions V1–V4 (fields, matching rules, generators) - provider/best_practices: provider how-to guide mirroring consumer.md depth (verification scope, selectors, provider states, CI setup) - plugins/concepts: Explanation of the plugin model, two plugin types, system actors, and decision guide (use vs build) All four pages wired into sidebars.json and concepts.md updated. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The 'How to write message pact tests' walkthrough was how-to content embedded in an explanation page. Extracted to consumer/how_to_test_async_messages.md and replaced with a two-sentence summary + link in how_pact_works.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Removed three embedded explanation sections that broke the tutorial's linear journey: consumer test scope, provider test scope, and the open-ended status code advice. Replaced intro with a clear outcome statement. Scope concepts are covered in testing-scope.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

pact_nirvana.md: explicit 'how-to guide' label in intro. step_1.md: replaced tutorial prerequisite voice ('Before you read this document, you should') with how-to 'Recommended reading' framing. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The 'Best practice' section in matching.md was how-to opinion content in a Reference page. Moved the 'avoid random data' point (new) to consumer.md and the request/response guidance is already covered there. Replaced the section with a link back to consumer.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The Matrix explanation at the top of can_i_deploy.md was Explanation content interrupting a How-to page. Replaced with a two-sentence problem statement and link to the broker overview. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Replaced tutorial narrative ('We'll start with...', 'Moving on...', 'Let's take a look...') with imperative headings and goal-first framing. Added problem statement, explicit tips, and preserved all technical content. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The 530-line Best Practice Guide was too large to live in consumer.md. Extracted to its own page with frontmatter. consumer.md now has a one-paragraph summary and link. Added to guides sidebar. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Added scoped intro paragraph explaining what the page covers and linking to related pages. Replaced 'I'll discuss later' forward reference with a direct link to can-i-deploy. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Phases 14 and 15 marked complete. Phase 16 (tone/style pass) and Phase 17 (housekeeping) added with per-page task list. DIATAXIS_REVIEW.md committed alongside. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ral, hedging Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ging Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ghout Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…oice Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The 2 remaining broken links are in implementation_guides/ (protected area, not in scope for this refactor) and were pre-existing before this branch. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

YOU54F · 2026-03-20T09:56:32Z

+  "providerStates": [
+    { "name": "product 10 exists" }
+  ],
+  "contents": {


this is invalid, there should be a messages array

https://github.com/pact-foundation/pact-specification/tree/version-3?tab=readme-ov-file#introduces-messages-for-services-that-communicate-via-event-streams-and-message-queues

ahh actually it is just showing an excerpt of an object entry in the messages array

YOU54F · 2026-03-20T10:01:36Z

+| V3 | `providerStates` as an array of objects. Message interactions. `generators`. V3 matching rule format. |
+| V4 | Plugin support. Combined interaction types (`Synchronous/HTTP`, `Asynchronous/Messages`, `Synchronous/Messages`). |


would be good to link here to each spec version

YOU54F

spent a short bit of time reviewing this morning with a coffee, good start, minor comments

YOU54F · 2026-03-20T10:05:23Z

+```ts
+// Top level - name of the API
+describe("Thing API", () => {
+  const pact = new PactV4({


This can just be new Pact( now

YOU54F · 2026-03-20T10:05:57Z

+  const pact = new PactV4({
+    consumer: "ThingConsumer",
+    provider: "ThingProvider",
+    spec: SpecificationVersion.SPECIFICATION_VERSION_V4,


spec version will default to 4 so we can remove this

YOU54F · 2026-03-20T10:07:34Z

like this, I think I remember this from the PF docs that you created. shame the sidebar doesn't list the rules

in fact, it is similar but not quite

YOU54F · 2026-03-20T10:12:06Z

+});
+```
+
+> ℹ️ Tip: Always provide example values when using generators like `uuid()`, `timestamp()`, or `dateTime()` to ensure stable contract output.


I almost feel like we should be warning the user here if they are doing this, as it seems like an easy trap. Is there rationale for having generators with random values?

YOU54F · 2026-03-20T10:20:13Z

+
+Consumer-driven contracts invert this. The consumer declares what it needs. The provider runs the consumer's expectations as its own tests. If the provider breaks a consumer's expectation, the provider's test suite fails — before deployment. The feedback loop is tight and automatic.
+
+This also addresses a common team-dynamics problem. Provider teams often don't know which of their consumers use which parts of the API. Consumer-driven contracts make this explicit: you can look at the pacts for a provider and see exactly which consumer calls which endpoint with which fields.


good lead in chance for bi-directional/provider-driven approach, and drift

YOU54F · 2026-03-20T10:21:11Z

+- **Is it safe to deploy this version?** The `can-i-deploy` command queries the broker's verification matrix and tells you, before you deploy, whether the version you're releasing is compatible with what's already in each environment.
+- **Who uses what?** The broker provides network graphs and dashboards that show the relationships between all registered services, making it easier to reason about the impact of changes.
+
+The broker is not required to use Pact. It is the piece that converts Pact from a testing tool into a deployment safety mechanism.


mefellows · 2026-03-20T11:22:54Z

@YOU54F sorry this isn't ready for review, please don't waste your time on it!

mefellows and others added 30 commits March 19, 2026 18:41

docs: update PLAN.md with completed phase progress

5a1b542

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

fe3e1e1

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

32b9597

Docusaurus strips numeric prefixes at runtime, so 01_Step1.md has doc ID 'Step1', not '01_Step1'. Revert sidebar references back to Step1..Step13 and Step1..Step4. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

23ea70d

Phases 14 and 15 marked complete. Phase 16 (tone/style pass) and Phase 17 (housekeeping) added with per-page task list. DIATAXIS_REVIEW.md committed alongside. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

9b02794

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

9dbfd78

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

93612bc

…ral, hedging Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

58d567b

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

dd57ebe

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

59fe710

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

01a4a31

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

66ddcf0

…ging Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

dfbfae0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

de5592e

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

f7e7f93

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

4c52bd8

…ghout Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

41c3519

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

mefellows and others added 4 commits March 20, 2026 16:12

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

7b19fb5

…oice Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

d4ba0fb

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

fc777b9

The 2 remaining broken links are in implementation_guides/ (protected area, not in scope for this refactor) and were pre-existing before this branch. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chore: finalise PLAN.md — Phase 17 complete

cdb26ed

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

YOU54F reviewed Mar 20, 2026

View reviewed changes

mefellows marked this pull request as draft March 20, 2026 11:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

mefellows commented Mar 20, 2026

Uh oh!

YOU54F Mar 20, 2026

Uh oh!

YOU54F Mar 20, 2026

Uh oh!

YOU54F Mar 20, 2026

Uh oh!

YOU54F left a comment

Uh oh!

YOU54F Mar 20, 2026

Uh oh!

YOU54F Mar 20, 2026

Uh oh!

YOU54F Mar 20, 2026

Uh oh!

YOU54F Mar 20, 2026

Uh oh!

YOU54F Mar 20, 2026

Uh oh!

YOU54F Mar 20, 2026

Uh oh!

YOU54F Mar 20, 2026

Uh oh!

mefellows commented Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		\| V3 \| `providerStates` as an array of objects. Message interactions. `generators`. V3 matching rule format. \|
		\| V4 \| Plugin support. Combined interaction types (`Synchronous/HTTP`, `Asynchronous/Messages`, `Synchronous/Messages`). \|


		Consumer-driven contracts invert this. The consumer declares what it needs. The provider runs the consumer's expectations as its own tests. If the provider breaks a consumer's expectation, the provider's test suite fails — before deployment. The feedback loop is tight and automatic.

		This also addresses a common team-dynamics problem. Provider teams often don't know which of their consumers use which parts of the API. Consumer-driven contracts make this explicit: you can look at the pacts for a provider and see exactly which consumer calls which endpoint with which fields.

Uh oh!

Conversation

mefellows commented Mar 20, 2026

Summary

What changed

Navigation restructure (Phases 1–13)

Content gaps filled (Phase 14)

Structural fixes (Phase 15)

Tone and style pass (Phase 16, T1–T15)

Bug fixes

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

YOU54F left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mefellows commented Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants