pact-foundation · mefellows · Mar 19, 2026 · Mar 19, 2026 · Mar 19, 2026 · Mar 19, 2026
diff --git a/DIATAXIS_REVIEW.md b/DIATAXIS_REVIEW.md
diff --git a/PLAN.md b/PLAN.md
@@ -0,0 +1,139 @@
+# Diataxis Refactor Plan — docs.pact.io
+
+## Status: In Progress
+Last updated: 2026-03-20
+
+---
+
+## 1. Audit Summary
+
+### Current navigation structure
+
+| Nav Item | Sidebar key | Description |
+|---|---|---|
+| Getting Started | `getting-started` | Landing, How Pact Works, 5-min guide, Pact Concepts, Workshops, FAQ |
+| Guides | `guides` | Consumer best practices, Provider best practices, Pact Nirvana (CI/CD), Recipes |
+| Pact Docs | `docs` | Implementation guides per language, CLI tools, Plugins, Feature support |
+| Pact Broker Docs | `pact_broker` | Broker admin, webhooks, can-i-deploy, etc. |
+| Resources | `resources` | History, blogs, books, events, case studies |
+| Contributing | `contributing` | Code, CI, docs, contributors |
+| Blog | (separate) | |
+| Help | `help` | How to ask for help, debug logging, SmartBear resources |
+| University | `university` | Intro to Pact (13 steps), Async messages (4 steps), Plugins workshop |
+
+---
+
+## 2. Key constraints
+
+- **DO NOT modify** anything under `website/docs/implementation_guides/` (Pact Docs)
+- **DO NOT modify** anything under `website/docs/pact_broker/` (Pact Broker Docs)
+- **DO NOT modify** anything under `website/blog/` (Blog)
+- **Add redirects** in `netlify.toml` for any URL changes
+
+---
+
+## 3. Implementation plan
+
+### Phase 1–13: Navigation and structural restructure ✅ COMPLETE
+All phases completed 2026-03-19. Summary:
+- 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 Diataxis signposting table to landing page
+- Added `/university` → `/tutorials` redirect in netlify.toml
+- Fixed pre-existing broken Step file references in tutorials sidebar
+- `further_reading` moved to Resources sidebar
+- `concepts.md` and `tutorials.md` landing pages created
+
+---
+
+### Phase 14: Diataxis review + content gaps ✅ COMPLETE (2026-03-20)
+
+Full Diataxis review conducted. Four content gaps identified and filled:
+
+- [x] **Gap 1** — `getting_started/why-pact.md` created: design philosophy explanation (consumer-driven contracts, generated pact files, broker model, trade-offs)
+- [x] **Gap 2** — `getting_started/pact-file-format.md` created: Reference page for pact JSON schema across spec versions V1–V4
+- [x] **Gap 3** — `provider/best_practices.md` created: provider how-to guide mirroring consumer.md depth
+- [x] **Gap 4** — `plugins/concepts.md` created: Explanation of the plugin model and system actors
+- [x] `concepts.md` updated with new entries for why-pact and pact-file-format
+- [x] All four pages wired into `sidebars.json`
+
+---
+
+### Phase 15: Structural fixes to existing content ✅ COMPLETE (2026-03-20)
+
+Eight type-mixing and framing issues fixed:
+
+- [x] **Fix 1** — `getting_started/how_pact_works.md`: extracted Message Pact how-to walkthrough → `consumer/how_to_test_async_messages.md`
+- [x] **Fix 2** — `5-minute-getting-started-guide.md`: removed embedded Explanation digressions (consumer scope, provider scope, status code advice)
+- [x] **Fix 3** — `pact_nirvana.md` + `step_1.md`: declared as how-to guide; removed tutorial prerequisite voice
+- [x] **Fix 4** — `getting_started/matching.md`: moved Best practice section to `consumer.md`; added "avoid random data" guidance
+- [x] **Fix 5** — `pact_broker/can_i_deploy.md`: replaced Matrix explanation with 2-sentence problem statement + link
+- [x] **Fix 6** — `recipes/kafka.md`: full rewrite with imperative headings and goal-first framing
+- [x] **Fix 7** — `consumer.md`: extracted 530-line Best Practice Guide → `consumer/best_practices.md`
+- [x] **Fix 8** — `getting_started/conceptual_overview.md`: added scoped intro; replaced "I'll discuss later" with direct link
+
+---
+
+### Phase 16: Tone and style consistency pass ✅ COMPLETE (2026-03-20)
+
+Rewrite in-scope pages for consistent tone and style:
+- Second-person voice throughout ("you", not "we" or "I")
+- Imperative framing in How-to pages
+- Neutral descriptive framing in Reference/Explanation pages
+- Remove hedging language ("you might want to", "it can be tempting to")
+- Remove filler openers ("Remember that...", "As you would hopefully have read")
+- Remove first-person author voice ("I'll discuss", "Let's walk through")
+- Consistent heading capitalisation (sentence case)
+
+Scope excludes `implementation_guides/`, `pact_broker/`, `blog/`, and pages written fresh in phases 14–15 (already consistent).
+
+#### Getting Started section
+- [x] **T1** — `getting_started.md` (landing page)
+- [x] **T2** — `getting_started/what_is_pact_good_for.md`
+- [x] **T3** — `getting_started/how_pact_works.md`
+- [x] **T4** — `getting_started/terminology.md` (already clean)
+- [x] **T5** — `getting_started/testing-scope.md`
+- [x] **T6** — `getting_started/verifying_pacts.md`
+- [x] **T7** — `getting_started/provider_states.md`
+- [x] **T8** — `getting_started/sharing_pacts.md`
+- [x] **T9** — `getting_started/comparisons.md` (already clean)
+
+#### FAQ
+- [x] **T10** — `faq.md` + `faq/convinceme.md`
+
+#### Consumer how-to
+- [x] **T11** — `consumer.md` + `consumer/contract_tests_not_functional_tests.md` + `consumer/using_pact_to_support_ui_testing.md` + `consumer/recommended_configuration.md`
+
+#### Provider how-to
+- [x] **T12** — `provider.md` + `provider/using_provider_states_effectively.md` + `provider/handling_auth.md` + `provider/recommended_configuration.md` + `provider/how_to_fix_failing_verification_tests.md`
+
+#### CI/CD Guide
+- [x] **T13** — `pact_nirvana/step_2.md` through `step_7.md`
+
+#### Recipes
+- [x] **T14** — `recipes.md` + `recipes/optional.md` + `recipes/graphql.md` + `recipes/apigateway.md` + `recipes/awssignedrequests.md` + `recipes/lambdaasync.md` + `recipes/lambdahttp.md` + `recipes/cypress.md` + `recipes/munit.md`
+
+#### Plugins
+- [x] **T15** — `plugins/quick_start.md` + `plugins/directory.md`
+
+---
+
+### Phase 17: Housekeeping ✅ COMPLETE (2026-03-20)
+
+- [x] Commit `DIATAXIS_REVIEW.md` (committed 2026-03-20)
+- [x] Final build verification — 2 pre-existing broken links remain in `implementation_guides/` (out of scope); 3 links fixed in concepts.md and step_1.md
+- [x] Review for any remaining orphaned pages — none found
+- [ ] PR / merge to master
+
+---
+
+## Progress log
+
+- [x] **2026-03-19**: Worktree created, PLAN.md written
+- [x] **2026-03-19**: Phases 2–13 — navigation restructure complete
+- [x] **2026-03-20**: Sidebar step ID regression fixed (`01_Step1` → `Step1`); site confirmed running
+- [x] **2026-03-20**: Phase 14 — four content gaps filled (4 new pages)
+- [x] **2026-03-20**: Phase 15 — eight structural fixes applied
+- [x] **2026-03-20**: Phase 16 — tone and style pass complete (T1–T15, 30+ files)
+- [x] **2026-03-20**: Phase 17 — housekeeping complete; 3 broken links fixed; PR pending
diff --git a/netlify.toml b/netlify.toml
@@ -225,3 +225,9 @@
   from = "/implementation_guides/pact_specification"
   to = "/getting-started/specification"
   status = 301
+
+# Diataxis refactor: /university landing page now redirects to /tutorials
+[[redirects]]
+  from = "/university"
+  to = "/tutorials"
+  status = 301
diff --git a/website/docs/5-minute-getting-started-guide.md b/website/docs/5-minute-getting-started-guide.md
@@ -9,7 +9,7 @@ description: From zero to running Pact tests in 5 mins
 :::
 
 
-This getting started guide can be run purely in the browser or on your local machine, with the intention to get you across the key concepts quickly. As we go through, there will be code snippets to demonstrate concepts. These are not runnable, but are there to assist with explanation. When there is code to run, you will be presented with a REPL as per below. Simply hit the green ▶ button, and the output will be displayed in the terminal below. Give it a shot now:
+This guide walks you through writing your first consumer and provider Pact tests end-to-end using a simple Order API example. By the end, you will have a generated pact file and a passing provider verification.
 
 ## Ways to run
 
@@ -41,16 +41,6 @@ Note that to create a pact, you _do_ need to write the code that executes the HT
 
 ## Testing the Order Web \(consumer\) project
 
-### Scope of a Consumer Pact Test
-
-Ideally, the Pact tests should be "unit tests" for your client class, and they should just focus on ensuring that the request creation and response handling are correct. If you use pact for your UI tests, you'll end up with an explosion of redundant interactions that will make the verification process tedious. Remember that pact is for testing the contract used for communication, and not for testing particular UI behaviour or business logic.
-
-Usually, your application will be broken down into a number of sub-components, depending on what type of application your consumer is \(e.g. a Web application or another API\). This is how you might visualise the coverage of a consumer Pact test:
-
-![Scope of a consumer Pact test](/img/consumer-test-coverage.png)
-
-Here, a _Collaborator_ is a component whose job is to communicate with another system. In our case, this is the `OrderApiClient`communicating with the external `Order Api` system. This is what we want our consumer test to inspect.
-
 ### 1. Start with your model
 
 Imagine a simple model class that looks something like this \(order.js\). The attributes for an Order live on a remote server, and will need to be retrieved by an HTTP call to the Order API.
@@ -234,14 +224,7 @@ Running the passing Order API spec will generate a pact file in the configured p
 
 You now have a pact file that can be used to verify your expectations of the Order API provider project.
 
-Now, in real life you would rinse and repeat for other likely status codes that may be returned. For example, consider how you want your client to respond to a:
-
-* 404 \(return null, or raise an error?\)
-* 400 \(how should validation errors be handled, what will the body look like when there is one?\)
-* 500 \(specifying that the response body should contain an error message, and ensuring that your client logs that error message will make your life much easier when things go wrong. Note that it may be hard to force your provider to generate a 500 error on demand. You may need to collaborate with your provider team to create a known provider state that will artificially return a 500 error, or you may just wish to use a standard unit test without a pact to test this.\)
-* 401/403 if there is authorisation.
-
-#### **Run the consumer Tests!**
+#### **Run the consumer tests!**
 
 OK enough talk - let's run the consumer test. If you like, click around the project to see the files from above in context. The most interesting file is the consumer test in `./consumer/consumer.spec.js` .
 
@@ -267,20 +250,6 @@ After publishing the pact, we can now verify that the Provider meets these expec
 
 ## Testing the Order API \(provider\) project
 
-### Scope of a Provider Pact Test
-
-On the Provider side, Pact needs to replay all of the interactions \(usually HTTP requests\) against your service. There are a number of choices that can be made here, but usually these are the choices:
-
-* Invoke just the controller layer \(in an MVC app, or the "Adapter" in our diagram\) and stub out layers beneath
-* Choosing a real vs mocked out database
-* Choosing to hit mock HTTP servers or mocks for external services
-
-Generally speaking, we test the entire service and mock out external services such as downstream APIs \(which would need their own set of Pact tests\) and databases. This gives you some of the benefits of an integration test without the high costs of maintenance.
-
-This is how you might visualise the coverage of a provider Pact test:
-
-![Provider side Pact test scope](/img/provider-test-coverage.png)
-
 ### 1. Create the Order API
 
 Below we have created a simple API using [Express JS](https://expressjs.com).

diff --git a/website/docs/concepts.md b/website/docs/concepts.md
@@ -0,0 +1,33 @@
+---
+id: concepts
+title: Pact Concepts
+description: Understanding how and why Pact works — the key concepts behind consumer-driven contract testing.
+---
+
+This section explains the **why** and **how** behind Pact. If you're new to contract testing or want to deepen your understanding of how Pact works, start here.
+
+## What you'll find here
+
+| Topic | Description |
+|---|---|
+| [Why Pact?](/getting_started/why-pact) | The design philosophy behind consumer-driven contracts, generated pact files, and the broker model |
+| [Conceptual overview](/getting_started/conceptual_overview) | A visual and narrative overview of the full Pact workflow |
+| [Terminology](/getting_started/terminology) | Definitions of key Pact terms: consumer, provider, pact, interaction, and more |
+| [Testing scope](/getting_started/testing-scope) | What Pact tests cover, and what it deliberately does not |
+| [Matching](/getting_started/matching) | How Pact compares requests and responses, and the types of matchers available |
+| [Provider states](/getting_started/provider_states) | How to set up the provider data needed for each interaction |
+| [Verifying pacts](/getting_started/verifying_pacts) | What happens when the provider runs verification |
+| [Sharing pacts](/getting_started/sharing_pacts) | How pact files flow between consumer and provider teams |
+
+## Reference
+
+| Topic | Description |
+|---|---|
+| [Pact specification](/getting_started/specification) | The Pact specification versions and what they support |
+| [Pact file format](/getting_started/pact-file-format) | The JSON structure of a pact file, including fields, matching rules, and generators |
+
+## Not sure where to start?
+
+- **New to Pact?** Start with the [Introduction](/) and [How Pact works](/getting_started/how_pact_works).
+- **Ready to write code?** Jump straight to [Tutorials](/tutorials).
+- **Solving a specific problem?** See [How-to Guides](/consumer).