claude-skills-reference/project-management/atlassian-templates/references/template-design-patterns.md

Template Design Patterns

Overview

Well-designed Confluence and Jira templates accelerate team productivity by providing consistent starting points for common documents and workflows. This guide covers design patterns, variable handling, and best practices for creating reusable templates.

Variable Placeholders

Confluence Template Variables

Syntax: <at:var at:name="variableName">default value</at:var>

Common Variables:

Variable	Purpose	Example Default
projectName	Project identifier	"Project Name"
author	Document author	"@mention author"
date	Creation or target date	"YYYY-MM-DD"
status	Current document status	"Draft"
version	Document version	"1.0"
owner	Responsible person	"@mention owner"
reviewers	Review participants	"@mention reviewers"

Best Practices:

• Use descriptive variable names (camelCase)
• Always provide meaningful default values
• Group related variables together
• Include instruction text that users should replace
• Use Status macro for status variables (visual clarity)

Jira Template Fields

Custom Fields for Templates:

• Text fields for structured input
• Select lists for controlled vocabularies
• Date fields for milestones
• User pickers for assignments
• Labels for categorization

Conditional Sections

Pattern: Role-Based Sections

Include or exclude content based on the document's audience:

## For Engineering (delete if not applicable)
- Technical requirements
- Architecture decisions
- Performance criteria

## For Design (delete if not applicable)
- User flows
- Wireframes
- Accessibility requirements

## For Business (delete if not applicable)
- ROI analysis
- Market context
- Success metrics

Pattern: Complexity-Based Sections

Scale content depth based on project size:

## Required for All Projects
- Problem statement
- Solution overview
- Success metrics

## Required for Medium+ Projects (>2 weeks)
- Detailed requirements
- Technical design
- Test plan

## Required for Large Projects (>1 month)
- Architecture review
- Security review
- Rollback plan
- Communication plan

Pattern: Optional Deep Dives

Use Expand macros for optional detail:

[Expand: Detailed Requirements]
  Content that power users may need but casual readers can skip
[/Expand]

Reusable Components

Header Block

Every template should start with a consistent header:

| Field | Value |
|-------|-------|
| Author | @mention |
| Status | [Status Macro: Draft] |
| Created | [Date] |
| Last Updated | [Date] |
| Reviewers | @mention |
| Approver | @mention |

Decision Log Component

Reusable across templates that involve decisions:

## Decision Log
| # | Decision | Date | Decided By | Rationale |
|---|----------|------|-----------|-----------|
| 1 | [Decision] | [Date] | [Name] | [Why] |

Change History Component

Track document evolution:

## Change History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | [Date] | [Name] | Initial version |

Action Items Component

Standard task tracking:

## Action Items
- [ ] [Task description] - @assignee - Due: [date]
- [ ] [Task description] - @assignee - Due: [date]

Macro Integration

Recommended Macros per Template Type

Meeting Notes Template:

• Table of Contents (for long meetings)
• Action Items (task list macro)
• Jira Issues (link to discussed tickets)
• Expand (for detailed discussion notes)

Decision Record Template:

• Status macro (decision status)
• Page Properties (structured metadata)
• Info/Warning panels (context and caveats)
• Jira Issues (related tickets)

Project Plan Template:

• Roadmap Planner (timeline view)
• Jira Issues (JQL for project epics)
• Children Display (sub-pages for phases)
• Chart macro (status distribution)

Runbook Template:

• Code Block (commands and scripts)
• Warning panels (danger zones)
• Expand (detailed troubleshooting)
• Anchor links (quick navigation)

Responsive Layouts

Two-Column Layout

Use Confluence Section and Column macros:

[Section]
  [Column: 60%]
    Main content, description, details
  [/Column]
  [Column: 40%]
    Sidebar: metadata, quick links, status
  [/Column]
[/Section]

Card Layout

For overview pages with multiple items:

[Section]
  [Column: 33%]
    [Panel: Card 1]
      Title, summary, link
    [/Panel]
  [/Column]
  [Column: 33%]
    [Panel: Card 2]
  [/Column]
  [Column: 33%]
    [Panel: Card 3]
  [/Column]
[/Section]

Brand Consistency

Visual Standards

• Use consistent heading levels (H1 for title, H2 for sections, H3 for subsections)
• Apply Info/Warning/Note panels consistently (same meaning across templates)
• Use Status macro colors consistently (Green=done, Yellow=in progress, Red=blocked)
• Maintain consistent table formatting (header row, alignment)

Content Standards

• Use the same voice and tone across templates
• Standardize date format (YYYY-MM-DD or your organization's preference)
• Use consistent terminology (define terms in a glossary)
• Include the same footer/metadata block in all templates

Versioning Strategy

Template Version Control

• Include version number in template metadata
• Maintain a changelog for template updates
• Communicate template changes to users
• Keep previous versions accessible during transition periods

Version Numbering

• Major (2.0): Structural changes, section additions/removals
• Minor (1.1): Content updates, improved instructions
• Patch (1.0.1): Typo fixes, formatting corrections

Migration Path

When updating templates:

1. Create new version alongside old version
2. Announce change with migration guide
3. New documents use new template automatically
4. Existing documents do not need to be migrated (optional)
5. Deprecate old template after 90 days
6. Archive old template (do not delete)

Template Catalog Organization

Categorization

Organize templates by:

• Document type: Meeting notes, decisions, plans, runbooks
• Team: Engineering, product, marketing, HR
• Lifecycle: Planning, execution, review, retrospective
• Frequency: One-time, recurring, as-needed

Discovery

• Maintain a "Template Index" page with descriptions and links
• Tag templates with consistent labels
• Include a "When to Use" section in each template
• Provide examples of completed documents using the template