Three layers of issue documentation
Every Jira issue has three native places to document. Each one is good at something different:
| Layer | Where | What belongs there |
|---|---|---|
| Issue description | The description field on the issue itself | What this specific issue is, why it exists, acceptance criteria, reproduction steps |
| Attachments | Files attached to the issue | Screenshots, log dumps, design mockups, one-off PDFs |
| Linked Confluence pages | Linked content on the issue + Confluence side | Anything other issues will also reference — architecture, specs, decisions, RFCs |
The decisive question: "Would I copy-paste this text into a second issue?" If yes, it belongs in Confluence with both issues linking to it. If no, it belongs in the description.
Layer 1 — the description field
The description is the only documentation that appears on the issue itself. Everything in it shows up when someone clicks the ticket. So treat it as the answer to "if a developer opens this issue cold, what do they need to know in the first 30 seconds?".
For a story or task, a good template is short:
- Context — one or two sentences on why this is in the backlog.
- Goal — what good looks like once it's done.
- Acceptance criteria — bullet list of testable conditions.
- Notes — links to related Confluence pages, prior tickets, design mockups.
For a bug, the template flips toward reproduction:
- Environment, browser/version, account or tenant.
- Steps to reproduce.
- Expected vs actual.
- Logs or screenshots (as attachments).
What does not belong in the description: architecture explanations, system overviews, project background. Those are the same on every ticket that touches the same module — that's the cue to move them to Confluence and link from each ticket instead.
Layer 2 — attachments
Attachments are easy to overuse. They're great for one-off evidence (a screenshot of the bug as it appeared, a log fragment, a design comp). They're bad for anything that will be referenced more than once, because they're discoverable only by opening the issue.
Practical rule: if an attachment matters to anyone who isn't already looking at this issue, it should be a Confluence page instead.
Layer 3 — linked Confluence pages
Confluence is the right home for any documentation that more than one issue will reference. The native Jira-Confluence integration handles the linking in both directions: link the page on the issue, and the issue appears under "Jira issues" on the Confluence page.
How to link a Confluence page to a Jira issue
- Open the Jira issue.
- Click Link (the chain icon) → Confluence page.
- Paste the page URL or search by title.
- Save. The page now appears under Linked content on the issue.
- Open the Confluence page — the issue shows up in the "Jira issues" macro section automatically if the page is in the same Atlassian site.
Common linking patterns
- Epic → spec page. Every epic links to its scoping/spec Confluence page. Stories under the epic don't need to repeat the link — it's reachable through the parent.
- Sprint → ceremonies page. The sprint's first issue links to the planning notes; the last issue links to the retro page.
- Bug → architecture context. A bug that touches a specific module links to the module's Confluence overview, so the dev fixing it has the context without trawling the codebase.
- Decision → decision log. When a ticket forces a non-obvious decision (which library, which API version, why a workaround), capture the decision on a Confluence page and link the page from the issue.
Keeping linked Confluence pages from going stale
The hardest part of this model isn't the linking — it's keeping the linked Confluence pages true. Once a page has 20 issues linked to it, the page becomes load-bearing, and the cost of it being wrong is no longer a single team's confusion.
Two patterns work:
1. Tie the page to a review cadence
For decision logs, RFCs, spec pages — the kind written for humans, by humans — assign the page an owner and a review interval (typically tied to the sprint or quarter where the linked epic closes). Confluence shows a "page last updated" date prominently; teams enforce that no page older than the threshold can be the source of truth.
2. Regenerate technical pages from source
For technical context — module overviews, API references, architecture summaries — the document the linked pages should describe is the code itself, and the source of truth is the repository. Manually keeping a Confluence page in sync with a moving codebase is a guaranteed loss.
CodeDoc AI for Confluence regenerates these pages from the source code automatically. Connect the repo, pick a preset (Developer Documentation, Onboarding Guide, Quick Reference, etc.), wire a webhook to a branch, and the Confluence page rewrites itself on every push. Any Jira issue linked to that page suddenly references documentation that is always current — without anyone in the team having to remember to update it.
The sweet spot: human-written decision logs reviewed on cadence, plus AI-regenerated technical pages updated on commit. Each Jira issue links to whichever applies. Stale links become impossible for the technical half, and the human half stays small enough to actually maintain.
What not to do
- Don't paste architecture diagrams into the description field. They go out of date inside a single sprint and nobody updates issue descriptions retroactively.
- Don't attach the same PDF to 20 issues. Upload it to Confluence once, link the Confluence page from each issue.
- Don't write the spec inside the epic description. Epics live for weeks; specs evolve in iterations. A spec belongs on a Confluence page that the epic links to.
- Don't rely on links between Jira tickets to convey context. Reading three linked tickets in sequence to understand what's going on is worse than reading one Confluence page.
Frequently asked questions
How do I document a Jira issue?
Use the description field for context, goal, and acceptance criteria specific to this issue. Use attachments for one-off evidence like screenshots or logs. Use linked Confluence pages for anything other issues will also reference — architecture, specs, decisions.
How do I link a Confluence page to a Jira issue?
On the Jira issue, click Link → Confluence page, then paste the URL or search by title. The page appears in the Linked content section of the issue, and the reverse link appears on the Confluence page automatically if the page is in the same Atlassian site.
Should I write documentation in the Jira description or in Confluence?
Description for content that only matters to this one issue. Confluence for content that other issues, other teams, or future readers will also need. Rule of thumb: if you would copy-paste the same text into a second issue, it belongs in Confluence.
How do I keep Confluence pages linked to Jira issues from going stale?
Two approaches. For pages written by humans (decision logs, RFCs, specs), assign an owner and a review cadence — Confluence shows the last-updated date prominently. For technical pages whose source of truth is the codebase, regenerate them automatically: CodeDoc AI rewrites the page from source on webhook or schedule, so the linked documentation stays current as the code changes.
Can I document multiple Jira issues in one Confluence page?
Yes — that's a common pattern for epics and project pages. Create the Confluence page with the broader context (scope, architecture, decisions), then link it from each related Jira issue. The page can also embed the Jira Issues macro to pull a live list of all linked tickets at the bottom.
Stop maintaining technical docs by hand
CodeDoc AI regenerates Confluence pages from your source code on every commit. Link the pages from your Jira issues once — they stay current automatically.
See CodeDoc AI →