# Operational system documentation in Confluence

Attach this file to the project conversation. Point to the parent Confluence page, existing materials, and repository. The agent compares them with the structure below, agrees the scope with the team, and prepares the content. If it has no writing access, it prepares material to paste and explicitly marks that the pages have not been saved.

This is documentation for operating and maintaining the system. Team working rules remain in the playbook, and task status in the accepted plan or Jira. Connect them with links; do not maintain several independent copies of the same rule.

## Set the framework before work begins

Prepare the documentation skeleton before the first task. Especially with an external team, you set expectations and ensure the project is transparent. The contractor completes agreed descriptions of its work, and someone on your side must check them when changes are accepted. Do not leave this until the end of the engagement.

- A company location available throughout the project and after the engagement ends: **[link and administrator on our side]**
- Agreed documentation scope: **[areas from structure 00–11 below]**
- Connection to the exit plan in the contract, meaning the plan for ending the engagement: **[scope of documentation and history handover, date, recipient, and verification method]**
- Who completes it on the contractor side and who checks it on our side: **[responsibilities]**
- When we check documentation together with a working change: **[acceptance point]**

Enter these agreements in the existing playbook or plan. Complete subsequent pages alongside decisions and implementation; at the beginning, do not invent answers that do not yet exist.

## Starting point

- System / product and boundaries of this description:
- New or existing project:
- Documentation home page in Confluence:
- Playbook, repositories, and existing plan:
- System version or initial state:
- Sources the agent may read:
- Agreed scope for creating or updating pages:

## Structure 00–11

For each area, record the link, person completing it, person checking it, person responsible for keeping it current, version, verification date, and open gaps.

| Area | What to describe | How to verify the content |
| --- | --- | --- |
| 00. Documentation map and owners | Pages, scopes, people, and completion status | A second person finds the knowledge and knows whom to report a gap to |
| 01. System architecture | Purpose, boundaries, system parts, dependencies, and reasons for decisions | Compare with code, configuration, and recorded decisions |
| 02. Systems, services, and repositories | What each element is responsible for and where its code is | Links lead to the correct sources |
| 03. Domain model and data | Concepts, rules, exceptions, meaning, and data flow | A person who knows the domain confirms rules and examples |
| 04. APIs and integrations | Inputs, outcomes, errors, and agreed contracts | Compare with implementation and a safe exercise or tests |
| 05. Infrastructure and environments | Where the system runs and where configuration is | Compare the description with the confirmed state |
| 06. Deployments, releases, and rollback | Decisions, versions, verification, and rollback | Evidence for the named version; account for data |
| 07. Monitoring and maintenance | Alerts, logs, recipients, and response | Safe exercise and recipient confirmation |
| 08. Backups and disaster recovery | What we back up and how we recover data | Result of a recovery exercise, date, and scope |
| 09. Testing and quality | Running checks, results, and known gaps | Version, actual results, and unperformed exercises |
| 10. Security and access | Roles and granting and removing access | Confirmation by the responsible person; without broadening access |
| 11. Operational instructions | Steps for problems, incidents, and maintenance | A second person follows the instructions in a safe environment |

Do not include passwords, tokens, keys, or customer data. If needed, point to an approved location for storing secrets, without their values.

## How we complete the documentation

### New project

1. Before work begins, create the home page and required subpages in the agreed location. Enter the known purpose, scope, responsibilities, and sources.
2. Once a decision is made, add it with its reason to the appropriate page. Mark a solution that has not been deployed as planned.
3. After completing a piece, add a description of how it works, its version, and verification results.
4. When accepting a stage, verify the related pages. Before releasing a version, complete the knowledge needed to use and maintain it.

### Existing system

1. Map current pages and gaps. Distinguish missing content, outdated content, contradiction, and confirmed knowledge.
2. First complete the areas needed for the change and critical to maintenance. Use code, configuration, tests, safe observations, and expert confirmations.
3. Record remaining gaps in the existing plan: what to complete, who is responsible, who will check it, and when you will return to it.
4. During modernization, separate the current and target state. After the change, check documentation for the new version.

## Content of an individual page

- Area, product, and version it applies to:
- Person completing / checking / keeping it current:
- Status: to be completed / to be checked / confirmed for version:
- Date and source of confirmation:
- What works today and why:
- What we are only planning:
- An instruction or example needed by the person using it:
- Check, actual result, and evidence:
- Gaps, contradictions, and next step from the existing plan:
- When the page requires an update:

“Confirmed” requires evidence and verification by the responsible person. If an area does not apply to the project, enter “not applicable” and a specific reason.

## Complete the first page from your own work

Take a feature you are currently planning or changing. Open its task, documentation, and code. The agent prepares content for the relevant Confluence page from these sources.

| Point in time | What we record |
| --- | --- |
| Before implementation | User need, agreed behavior, exceptions, and reasons for decisions; marked as a plan if they do not work yet |
| After showing the change | How the user uses the feature, demo result, and open feedback |
| After verification | Version, exercises performed, results, and person checking it |
| After release | Confirmed state in the target environment and the required operating or maintenance instruction |

### When an old description disagrees with the application

Record side by side the specific document fragment and result of an exercise on the current version. Attach sources. Ask the person who knows the rule which outcome is correct and why. Until an answer, mark the difference as unresolved.

After an answer, add the decision, rationale, person, and date. If code needs to change, connect the decision to a task. Do not change the description of the current state to the target state while the application still works the old way. Only after the change and verification, record the new state.

**Verification:** give the page to a person who did not take part in the conversation. Have them explain how the feature works, identify an exception, and say what is not yet resolved. Complete gaps on that same page.

## Prompt for completing the documentation

```text
Read this template and the permitted sources: [links]. First create a map of
existing pages and gaps. For every completed fragment, give the source,
version, date, and person checking it. Separate the current state from the plan.
For a contradiction, record both sources and a question for the owner, without guessing.
Prepare content for shared agreement and identify the correct Confluence page.
Do not save pages or change access, accounts, environments, or external services.
```