# Documentation Plan: [Product or release name]

> Plan for the user and developer documentation of a product or release:
> audiences and their tasks, deliverables, structure, style, tooling,
> review, localisation, accessibility, maintenance and success measures.
> Based on common industry practice for documentation planning. Replace
> every `[bracketed]` value and every row marked *Example*.

<!--
Guidance: How to use this template
- Start from audiences and their tasks, not from a list of documents.
  Deliverables exist to support tasks; anything that supports no task is
  a candidate to cut.
- Agree the plan with product, engineering and support before writing.
  The plan is a commitment about scope, owners and dates.
- Keep it short and current. Update the deliverables inventory weekly
  during the release and archive the plan when the release ships.
- Make every row owned: a deliverable without an owner will not ship.
-->

| Field | Value |
|---|---|
| Product / release | [Product name] [4.0] |
| Plan version | [0.1] |
| Status | [Draft / Agreed / Closed] |
| Documentation lead | [@docs-lead] |
| Stakeholders | [@product-manager], [@engineering-lead], [@support-lead] |
| Release date | YYYY-MM-DD |
| Last updated | YYYY-MM-DD |

## 1. Purpose and scope

<!-- Guidance: Say what the plan covers and what it deliberately leaves out, for example marketing copy or internal engineering notes. -->

This plan covers the documentation needed for [Product name] [4.0]:
end-user help, administrator and installation guides, API documentation
and release notes. It does not cover [marketing pages, sales enablement
material, internal design documents], which are owned by [teams].

Goals for this release:

- *Example:* Every new feature has task documentation on release day.
- *Example:* Reduce "how do I" support tickets for the import feature by 30%.
- *Example:* Publish the API reference generated from the OpenAPI file.

## 2. Audiences and their tasks

<!-- Guidance: Name each audience, what they already know, and the top tasks they need documentation for. Use research: support tickets, search logs, interviews. -->

| Audience | Prior knowledge | Top tasks | Where they look |
|---|---|---|---|
| *Example:* New end user | Uses web apps; new to the product | Sign up, import first file, share a document | In-app help, search engine |
| *Example:* Workspace admin | Familiar with SSO and user management | Configure SSO, manage seats, export audit log | Admin console help, PDF guide |
| *Example:* Integrating developer | REST APIs, one of Python or JavaScript | Authenticate, create items, receive webhooks | Developer portal, GitHub |
| *Example:* Support agent | Expert user | Diagnose errors, find the right article to send | Internal knowledge base |
| [Audience] | [Knowledge] | [Tasks] | [Channels] |

## 3. Deliverables inventory

<!-- Guidance: One row per deliverable. Type follows the Diátaxis split (tutorial, how-to, reference, explanation) or your own content types. Track status here weekly. -->

| ID | Deliverable | Type | Audience | Owner | Format | Due | Status |
|---|---|---|---|---|---|---|---|
| DOC-01 | Getting started tutorial | Tutorial | New end user | [@writer-a] | Web help | YYYY-MM-DD | [Not started / Drafting / In review / Published] |
| DOC-02 | Import data how-to set (5 articles) | How-to | End user | [@writer-a] | Web help | YYYY-MM-DD | [Status] |
| DOC-03 | SSO configuration guide | How-to | Admin | [@writer-b] | Web help + PDF | YYYY-MM-DD | [Status] |
| DOC-04 | API reference | Reference | Developer | [@api-team] | Generated from OpenAPI | YYYY-MM-DD | [Status] |
| DOC-05 | Webhooks concepts | Explanation | Developer | [@writer-c] | Developer portal | YYYY-MM-DD | [Status] |
| DOC-06 | Release notes 4.0 | Release notes | All | [@docs-lead] | Web, in-app | YYYY-MM-DD | [Status] |
| DOC-07 | In-app empty-state and error text | UI text | End user | [@ux-writer] | Product strings | YYYY-MM-DD | [Status] |
| [DOC-nn] | [Deliverable] | [Type] | [Audience] | [@owner] | [Format] | YYYY-MM-DD | [Status] |

Effort estimate: [about 45 writer-days], based on roughly 1.5 days per new
task article and 0.5 days per updated article.

## 4. Information architecture

<!-- Guidance: Show how readers will navigate: top-level sections, where new content goes, and how pages link. Keep the structure aligned with tasks, not with the org chart. -->

The help centre is organised by audience, then by content type:

```mermaid
flowchart TD
    H["Help centre"] --> U["Use the product"]
    H --> A["Administer"]
    H --> D["Develop"]
    U --> U1["Get started (tutorials)"]
    U --> U2["How-to guides"]
    U --> U3["Troubleshooting"]
    A --> A1["Install and configure"]
    A --> A2["Security and SSO"]
    D --> D1["Guides"]
    D --> D2["API reference"]
```

Rules: each page has one type; every how-to links to the reference it
uses; every error message in the product links to a troubleshooting entry.

## 5. Style and terminology

<!-- Guidance: Name the style guide and the terminology source. List new terms introduced in this release so writers, UI and support use the same words. -->

- Style guide: [Technical Writing Style Guide, version 2.1].
- Terminology source: [product glossary link]; the UI wins when terms conflict.

| New term | Definition | Do not use |
|---|---|---|
| *Example:* Workspace | Top-level container for a team | Organisation, tenant (in user docs) |
| *Example:* Import job | A single run that brings data in | Upload, sync |
| [Term] | [Definition] | [Rejected variants] |

## 6. Tools and publishing pipeline

<!-- Guidance: List tools, where sources live, how content is built and published, and who can publish. -->

| Stage | Tool | Notes |
|---|---|---|
| Authoring | Markdown in `docs/` repository | Same pull-request flow as code |
| Diagrams | Mermaid in source | Rendered at build time |
| API reference | Generated from `openapi.yaml` | Fails the build on undocumented fields |
| Build and checks | Static site generator, link checker, spell checker, Vale-style linter | Runs on every pull request |
| Publishing | CI deploy on merge to `main` | Preview URL for every pull request |

## 7. Review and approval workflow

<!-- Guidance: Define who reviews what, in which order, and the turnaround you expect. Technical review catches errors; editorial review catches clarity problems. -->

| Step | Reviewer | Checks | Turnaround |
|---|---|---|---|
| 1. Self-review | Author | Checklist from the style guide; steps tested | Before pull request |
| 2. Technical review | Feature engineer | Accuracy, completeness, code samples run | 2 business days |
| 3. Editorial review | Peer writer | Clarity, style, terminology, structure | 2 business days |
| 4. Product sign-off | Product manager | Matches shipped behaviour and messaging | 1 business day |

Content is published only when steps 1 to 3 are complete; step 4 is
required for release notes and new tutorials.

## 8. Localisation

<!-- Guidance: Say which languages, which deliverables, the timing relative to English, and how source text is prepared for translation. -->

| Language | Deliverables | Timing |
|---|---|---|
| [German, French, Japanese] | DOC-01, DOC-02, DOC-06, DOC-07 | Within [10] business days after English |
| [Spanish] | DOC-06, DOC-07 | Within [15] business days |

Preparation rules: freeze English source before hand-off; no text in
images; keep UI terms in a translation memory; allow about 30% text
expansion in layouts.

## 9. Accessibility

<!-- Guidance: State the accessibility target for documentation and how it is checked. Documentation is part of the product's accessibility. -->

All published documentation targets [WCAG 2.2 level AA]. Checks per
pull request: heading order, alt text on every image, descriptive link
text, tables with header rows, code blocks with a language label, and
colour contrast in diagrams. Videos need captions and a transcript.

## 10. Maintenance and versioning

<!-- Guidance: Explain how docs stay correct after release: versioning, ownership, review cycles, and archiving. -->

- Docs are versioned with the product; the latest two major versions
  stay online, older ones are archived with a banner.
- Each page has an owner in its front matter and is reviewed at least
  every [12 months] or when its feature changes.
- Feedback from the "Was this helpful?" widget and support tickets is
  triaged weekly by [@docs-lead].

## 11. Metrics

<!-- Guidance: Choose a few measures tied to the goals in section 1, with a baseline and a target. Page views alone do not show success. -->

| Metric | Baseline | Target | Source |
|---|---|---|---|
| *Example:* Support tickets tagged "how do I" for import | 120 per month | 84 per month (-30%) | Support tool |
| *Example:* Helpful rating on new articles | n/a | 80% or higher | Feedback widget |
| *Example:* Searches with no result | 9% | Below 5% | Site search logs |
| *Example:* Deliverables published by release day | n/a | 100% of DOC-01 to DOC-07 | This plan |

Helpful rating is computed as $\frac{\text{yes votes}}{\text{yes votes} + \text{no votes}}$
over articles with at least 30 votes.

## 12. Risks and dependencies

<!-- Guidance: Name what could stop the plan and what you will do about it. -->

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| *Example:* Feature UI changes after docs are drafted | High | Medium | Draft after UI freeze; screenshots last |
| *Example:* Engineers unavailable for technical review | Medium | High | Book review time in sprint planning |

## Standard and licence note

Based on common industry practice for documentation planning in
software product teams. Template licence: MIT.