Master this essential documentation concept
The suite of interconnected software tools made by Atlassian, including Jira and Confluence, which share integrations, user management, and data to create a unified development and collaboration workflow.
The suite of interconnected software tools made by Atlassian, including Jira and Confluence, which share integrations, user management, and data to create a unified development and collaboration workflow.
When your team onboards new members or rolls out changes across your Atlassian ecosystem, the go-to approach is often a recorded walkthrough — a Confluence setup demo, a Jira workflow explanation, or a screen-share showing how your tools connect. These recordings capture real institutional knowledge, but they create a quiet documentation problem over time.
The challenge is that your Atlassian ecosystem is deeply interconnected. When someone needs to understand how your Jira project configurations link to Confluence spaces, or how user permissions cascade across both tools, scrubbing through a 45-minute onboarding recording is rarely practical. That context gets lost, and teams end up asking the same questions repeatedly or recreating work that was already explained in a video nobody can find.
Converting those recordings into structured, searchable documentation changes how that knowledge lives in your workflow. A recorded admin session explaining your Atlassian ecosystem's permission scheme, for example, becomes a referenceable doc your team can search, link to from Confluence, or attach directly to a Jira ticket — right where the question actually comes up.
If your team relies on video to document how your tools are configured and connected, see how you can turn those recordings into documentation your whole team can actually use.
Engineering teams lose context switching between Jira sprint boards and scattered Google Docs or Word files for PRDs, causing misalignment between what was planned and what was built.
Confluence pages can be directly linked to Jira Epics and Stories using the native Jira Issues macro, so requirements, acceptance criteria, and architecture decisions live alongside the backlog items they describe.
["Create a Confluence space for the product area (e.g., 'Payments Platform') and add a PRD template page for each Epic.", "Inside the Confluence PRD page, insert the 'Jira Issues' macro filtered by the Epic's key (e.g., PAY-42) to display live issue status.", "In Jira, navigate to the Epic and add the Confluence page URL in the 'Confluence Pages' panel under the issue's details tab.", 'Configure Confluence page restrictions so only the product squad has edit access, while the broader org has view access for transparency.']
Developers and PMs reference a single source of truth — the Confluence PRD shows live Jira ticket status, reducing standup clarification questions by eliminating version-mismatch confusion between specs and the backlog.
After production incidents, SRE teams spend hours manually copying incident timelines from Jira Service Management tickets into Confluence postmortem templates, delaying the blameless review process and causing data inconsistencies.
Jira Automation rules can trigger Confluence page creation from a resolved JSM incident ticket, pre-populating the postmortem template with incident metadata like severity, duration, and affected services.
["Build a Confluence postmortem template in the 'Engineering Runbooks' space with placeholder variables for incident ID, severity, and timeline.", "Create a Jira Automation rule in JSM triggered when an incident ticket transitions to 'Resolved' with priority P1 or P2.", "Use the 'Create Confluence Page' automation action, mapping JSM ticket fields (summary, description, resolution time) to the template variables.", 'Add a final automation step that posts a Slack notification with the generated Confluence page link to the #incidents channel.']
Postmortem pages are generated within seconds of incident resolution, with accurate metadata pre-filled, allowing the SRE team to begin the blameless review meeting with a structured document rather than a blank page.
New engineers joining a squad spend their first two weeks asking senior developers for context on past architectural decisions, codebase conventions, and team norms because this knowledge is buried in old Slack threads or undocumented entirely.
Confluence serves as the structured knowledge base for architectural decision records (ADRs), team norms, and runbooks, while Jira provides a curated 'Onboarding' epic with starter tasks that link directly to relevant Confluence pages.
["Create a Confluence 'Engineering Onboarding Hub' page tree with sections for ADRs, coding standards, local dev setup guides, and team rituals.", "Build a Jira Epic template called 'New Engineer Onboarding - [Name]' containing 10–15 predefined Stories such as 'Set up local dev environment' and 'Read the API design ADR'.", "Embed Confluence page links inside each Jira Story's description field so the task and its reference documentation are co-located.", 'Assign the Jira epic to the new hire on day one and schedule a Confluence page review checkpoint at the end of week two.']
New engineers achieve their first production code merge within 5 days on average, and senior developer interruptions for onboarding questions drop significantly because answers are discoverable through the linked Jira-Confluence trail.
When multiple squads depend on a shared internal API, breaking changes in Bitbucket pull requests go unnoticed by consuming teams because there is no system connecting code changes to the API documentation that downstream teams reference.
Bitbucket pull requests can be linked to Confluence API documentation pages, and Jira tickets for breaking changes can be flagged with a 'Breaking Change' label that triggers notifications to dependent teams via Jira Automation.
["Maintain the internal API reference as a Confluence page in a shared 'Platform APIs' space, using the OpenAPI Swagger macro to render the spec inline.", "Establish a team convention: every Bitbucket PR that modifies an API contract must include the related Jira ticket key in the PR title (e.g., 'PLAT-88: Deprecate v1 /users endpoint').", "Create a Jira Automation rule that watches for issues labeled 'breaking-change' and automatically comments on the linked Confluence API page with a deprecation notice banner.", 'Set up Confluence page watchers so all squad leads subscribed to the API page receive email notifications when the page is updated by the automation.']
Consuming teams receive automated deprecation notices on the Confluence API page before the breaking change merges, reducing production incidents caused by undiscovered API contract changes across squad boundaries.
Running multiple disconnected Atlassian Cloud sites creates fragmented user directories, making it impossible to consistently revoke access when employees offboard or change roles. Consolidating all products under one Atlassian Access organization enables SCIM provisioning from your identity provider (Okta, Azure AD) so user lifecycle is automated. This also enables cross-product analytics in Atlassian Admin to audit who has access to what.
Structuring Confluence spaces around business units (e.g., 'Engineering Department', 'Marketing Department') causes documentation to become siloed and disconnected from the actual work tracked in Jira. Mapping Confluence spaces to Jira project keys (e.g., a 'Payments Platform' Confluence space for the PAY Jira project) keeps documentation co-located with the work it describes. This alignment makes the Jira Issues macro and cross-product search far more effective.
Documentation staleness is one of the most common failures in the Atlassian ecosystem — a Confluence runbook references a Jira Epic that was closed months ago, or an architecture page describes a system that has since been deprecated. Jira Automation rules can add warning banners or update page labels in Confluence when linked Jira Epics are marked 'Done' or 'Cancelled'. This creates a living documentation system rather than a static archive.
When teams independently install Marketplace apps (e.g., draw.io for Confluence, Tempo Timesheets for Jira) on their own sites without central governance, the organization accumulates redundant, overlapping, and sometimes conflicting tools that drain budget and create data silos. Establishing an app governance process through Atlassian Admin ensures apps are evaluated for security, compliance, and duplication before installation. Centrally managed apps also ensure consistent data schemas across teams.
Without Smart Commits enabled, developers must manually transition Jira issues from 'In Progress' to 'In Review' or 'Done' as they push code and merge pull requests, creating a constant lag between actual work state and Jira board state. Enabling the Jira-Bitbucket integration with Smart Commits allows commit messages like `git commit -m 'PAY-88 #resolve Fixed null pointer in checkout'` to automatically close the Jira issue. This keeps sprint boards accurate in real time without developer context switching.
Join thousands of teams creating outstanding documentation
Start Free Trial