Create and maintain Confluence documents#

Use this guide to keep shared SKAO documentation useful and discoverable.

Find the right space#

Use the page tree and space search to find related content before creating a page. Add team-specific working material to the relevant team space. Add planned architecture or requirements to Solution Intent. Keep implementation details that must stay in step with code in the repository.

For Solution Intent contributions, start in the product or component area that matches the work. Use the contribution guidance linked from the Solution Intent home page and contact the owner of the relevant product page when you cannot identify the right location.

Create or update a page#

Select Create to start a blank page, or copy a suitable existing page when it provides a useful structure. Confluence creates the page in the current location by default. Select the page-location icon beside the breadcrumbs to choose another space or parent page.

Use a descriptive title and explain the page’s purpose in the opening paragraph. Link to related Jira issues, GitLab projects, source documentation, or Developer Portal pages where they help readers reach the source of truth.

Add a Jira issue or filter#

Use the Jira Issue/Filter macro when the page explains or records work tracked in Jira. Open the macro selector with Ctrl+Shift+J, select Jira Issue/Filter, then search by issue key, URL, Jira link, JQL query, or text.

The macro is optional, but it lets readers see the linked issue and its current status without leaving the page.

Format long or technical pages#

Add a Table of Contents macro near the start of a long page. Use a Code Block macro for commands, configuration, code, and XML. Select the syntax-highlighting language that matches the content.

Do not put credentials, tokens, passwords, or private variables in a Confluence page or code block.

Keep content current#

Correct content directly when you own it or have the required access. Otherwise, leave an inline comment or contact the page owner. Replace duplicated implementation details with a link to the maintained repository documentation when possible.

Keep Solution Intent material current as the design and implementation evolve. Update it when intended requirements, architectural guidance, decision records, implementation pointers, configuration snapshots, or validation evidence change.

Publish and manage restrictions#

Select Publish to make a new page available and Update to save changes to an existing page. Pages are normally visible and editable to everyone with the required space permissions. Restrict a page only when there is a clear need to limit access.

Only the page creator or owner can delete it. Contact the page owner or a space administrator if you cannot change a restriction or delete an obsolete page.

Was this page helpful?