System documentation in Confluence

The playbook explains how the team works. Operational documentation describes how the system works, how to develop it, and what to do when a problem occurs. You need both. A list of empty Confluence pages does not yet help with work.

My lesson: documentation starts before the first task

I learned this lesson while delivering a project with an external software house. Documentation existed, but its structure emerged ad hoc.

Prepare the documentation skeleton at the very beginning of the project, especially when you start with an external team. You are responsible for the project’s clarity and for setting the collaboration framework. Do not assume the contractor will work out which documentation you need.

My lesson is simple: if you do not set the framework at the beginning, you will get weak documentation at the end. Before the first task, agree with the team:

• Where you record knowledge — a company account and space, administered on your side, with access throughout the project and after collaboration ends.
• What must be described — a page skeleton you complete as decisions and delivery proceed.
• Who completes and who checks it — on both the contractor’s side and yours.
• When you check currency — at acceptance of successive changes, not only when collaboration ends.

The external team is accountable for agreed descriptions of its work. You set the expectations and ensure documentation is actually created. You do not need every answer at the beginning. You must know where you will record answers and who owns them. The other contractor-collaboration lessons explain why tools, domains, and cloud must be company-owned from the start and what to agree in the exit plan.

Prepare the structure and accountable people

I used the following structure in my documentation. You can use it in your project, adjusting scope to the system. If documentation already exists, assign its pages to these areas:

• 00. Documentation map and owners — where knowledge is, who completes it, who checks it, and when it was last compared with the system.
• 01. System architecture — what the system consists of, how parts cooperate, and why this solution was chosen.
• 02. Systems, services, and repositories — where each component’s code is and what it is responsible for.
• 03. Domain model and data — product concepts, rules, exceptions, and the meaning of stored data.
• 04. APIs and integrations — how systems exchange data, what they expect from one another, and what happens on error.
• 05. Infrastructure and environments — where the application runs, each environment’s purpose, and where its configuration is.
• 06. Deployments, releases, and version rollback — how to start a change, check it, and return to the previous state.
• 07. Monitoring and maintenance — how you notice a problem, where to seek its cause, and who responds.
• 08. Backups and disaster recovery — what is copied, how to recover data, and when it was checked to work.
• 09. Tests and quality — what and how you check, where results are, and what remains unchecked.
• 10. Security and access — who should have access, how to give and remove it, and where data-protection rules are. No passwords or tokens.
• 11. Operational instructions — concrete steps, for example after an alert, integration failure, or failed deployment. Such instructions are also called runbooks.

Every page has a person responsible for keeping it current and someone who confirms its content. Add date, system version, and sources. Use simple labels: to complete, to check, confirmed for version. If an area does not apply to the project, record why. Distinguish a planned solution from what already works.

New project: complete it as you work

Before work begins, create the main Confluence page and needed child pages. Immediately enter what you have already agreed: goal, system scope, responsible people, and repository and plan links. Complete the rest when you make decisions and build successive parts.

After selecting a solution, the agent adds architecture and rationale. After adding an integration, it adds the data-exchange method. After preparing deployment, it adds the launch and rollback instruction. At stage acceptance, also check the related pages. Documentation needed for safe use and maintenance of a version must be completed before it is handed over.

Existing system: find gaps and fill them

First compare the map with current documentation. Mark what exists, what is missing, what conflicts, and what needs checking. Materials from the prior team or contractor are sources to verify: they may describe an old system version.

Complete knowledge using code, configuration, tests, safe trials, and conversations with people who know the domain. Start with areas required for the nearest change and critical to maintenance. Give remaining gaps an owner and a place in the existing plan. Do not stop at listing them.

During modernization, separate the description of what works today from the target solution. After switching a system slice, update documentation of the actual state. Do not infer the historical reason for a decision from code alone.

When document, code, and expert say different things

If an instruction describes behaviour different from the application, record the discrepancy with the changed feature. The agent should show both sources and reproduce the case in a safe preview. Code alone will not explain whether this is a defect or an old decision that no one added to documentation.

Mark this slice unresolved until it is explained. After the rule owner responds, add the decision and required test. At acceptance, open the page beside the demo: does it describe the version shown? The downloadable file includes a template for recording a discrepancy and next steps.

Give the agent a structure to fill

Download the file, attach it to the project conversation and point to the location in Confluence. If the agent has the right access, it may create or update pages after the scope is agreed. Otherwise, it will prepare content to paste and say where it belongs. Preparing text alone does not mean it has been saved in Confluence.

Prepare operational documentation for system [name] in Confluence [parent page] with us. The project is [new / existing]. Read the attached file, playbook, and available sources [links]. First check access and compare the proposed structure with current pages. Show which pages you will use, what must be completed, and what cannot yet be confirmed. Do not create duplicates. For each area, agree with us who completes the content, checks it, and keeps it up to date. After scope is agreed, fill pages with confirmed knowledge. Give source, version, and date; separate a plan from the running system. Ask about gaps rather than inventing content. Put remaining work in the existing plan and return to it during delivery. Before stage acceptance, check pages about that change. Do not call content confirmed merely because you generated it. If you cannot save pages in Confluence, prepare content to paste and say what remains to be saved. Do not include secrets.

Check documentation in use

A second person should find the repository, understand an important rule, and follow a needed instruction in a safe environment. A backup description needs evidence of a restoration trial; a deployment description needs evidence of a version check. Text alone does not prove those trials happened.

Result: Confluence contains completed, checked knowledge needed at this stage. Open gaps are visible and have an owner and next step. Documentation changes with the system.