How-To2026-08-2810 min read

How to Create an Engineering Wiki in Confluence

Confluence is the natural wiki for teams using Jira because its Jira macro integration lets wiki pages display live ticket status, show active sprints, and link directly to project boards. When set up correctly, the engineering wiki becomes the connective tissue between documentation and execution — not a separate artifact that drifts from reality.

This guide covers how to structure an Engineering Confluence space, which macros to use for dynamic content, how to set up page templates, and how to maintain the wiki as the engineering team and system evolve.

Step-by-step guide

01

Create an Engineering Confluence space

Create a dedicated Confluence space (not just a section of a shared space) called "Engineering." In Space Settings, configure the space home page to serve as the wiki landing page with four navigation cards: Getting Started, Architecture & ADRs, Services & Runbooks, and Development Practices. Use the Confluence Page Tree to organize child pages under each section. The Space home page should be a navigation hub, not a dumping ground for recent content.

02

Set up the Services catalog using Page Properties

Create a "Services" parent page. Under it, create one child page per service named after the service. In each service page, add a Page Properties macro at the top containing: Owner, Team, Status (Active/Deprecated), Primary Language, and Repository Link. On the parent Services page, add a Page Properties Report macro that auto-generates a sortable table of all services with their properties. This creates a live services catalog that updates automatically as service pages are added or edited.

03

Create runbook templates using page blueprints

Go to Space Settings > Blueprints > Create a new blueprint called "Runbook." Add the runbook structure as the template body: Overview, Prerequisites, Steps (numbered with expected output), Verification, Rollback, and Contacts. Engineers create new runbooks using Create > From Blueprint rather than blank pages. Blueprints ensure every runbook has the same structure, making them scannable under pressure during incidents.

04

Add Jira macros for live context

On the space home page, add a Jira Issues macro configured to show the current active sprint and any open critical bugs. On service pages, add Jira Issues macros filtered by the service's Jira label showing open incidents and tech debt items. This makes the wiki dynamic — service pages show current Jira context without manual updates. Engineers stop needing to switch between Confluence and Jira for basic status.

05

Configure space permissions and ownership

Set space permissions so all engineers have Edit access (not just View). Create a space admin role for the EM or a designated wiki owner who manages the overall structure. Add a Page Ownership label to each page and create a Confluence view filtered to pages where the Last Updated date is more than 90 days ago — review these monthly with page owners. Without explicit ownership, pages rot.

Common mistakes

Using Confluence like a file system instead of a wiki

Creating deep nested folder hierarchies (Engineering > Backend > Services > Auth > Documentation > Runbooks > 2026) makes content impossible to find. Confluence pages are searchable — use labels and Page Properties for filtering rather than folder depth. Keep the tree shallow (3 levels maximum) and rely on search and macros for navigation.

Not using blueprints for recurring page types

Engineers creating ADRs, runbooks, and postmortems from blank pages produce inconsistently structured documents. Confluence blueprints solve this: one blueprint per document type, required in team guidelines. This is the difference between a wiki that is searchable and consistent versus one that requires interpretation to extract value.

Overloading the space home page with recent activity

The default Confluence space home page shows "Recently Updated" — a chronological list of the last changes. This is useful for active contributors but useless for engineers looking for a specific runbook or architecture doc. Replace it with a structured navigation page using cards, macros, and clear links to the main wiki sections.

Tips

Add a "Documentation needed" Jira ticket type or label that engineers can use during sprint work to flag gaps in the wiki. Route these to the wiki owner weekly so documentation debt is tracked alongside tech debt.

Use Confluence's Analytics feature (in Premium) to identify pages with high views but poor ratings — these are likely outdated or incomplete pages that are being found but failing to help engineers.

Create a "New Engineer Reading List" Confluence page that links to the 15-20 most important wiki pages in order — this gives new engineers a structured onboarding path through the wiki.

How Vantage helps

Confluence engineering wikis capture technical context. Vantage connects that context to active product work: when a PRD references a service or architectural component, Vantage can pull the relevant Confluence service page and ADRs as grounding context during requirement generation. Engineers and PMs working in Vantage get the technical constraints from the wiki without leaving their workflow.

Frequently asked questions

Spend less time on setup, more on decisions

Vantage connects your tools and generates specs grounded in real data. Free to start.

Free to start. No credit card required.

Related reading