120 posts tagged with "confluence"

The onboarding doc says "check the architecture diagram" and the architecture diagram shows a monolith from 2023 that the team decommissioned in the spring. Nobody is lying — the draw.io file lives on one person's laptop, and the wiki holds a screenshot nobody owns. An architecture that only exists as a static export rots silently, because the thing you would edit is invisible to review.

Quick answer: document system architecture in Confluence as Mermaid text — C4Context for the system in context, architecture-beta for the deployment, block-beta for the topology you want laid out precisely — rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Every level stays an editable code block, so the wiki's architecture changes in the same review that changes the system. This post gives you three copy-paste examples.

The quarterly review loads a 14-tab spreadsheet to answer one question — "where do we actually spend our engineering time?" — because the wiki charts are stale screenshots from last quarter and the numbers table nobody reads. A dashboard is not a spreadsheet: it is the two charts that answer the two questions people keep asking.

Quick answer: build dashboard charts in Confluence with Mermaid pie and xychart-beta charts, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Pie for shares, XY for trends — both as editable text that refreshes like code. This post gives you three copy-paste examples: an effort-share pie, a weekly trend XY, and a dual-series release dashboard.

A build fails at 4pm, and the fix's pipeline takes 40 minutes to re-run from the top because someone decided every stage needs to re-validate. That wasted hour is not a code problem — it is a documentation problem. Nobody could see the pipeline's shape, so nobody saw the retry loop and the gate that would have caught the failure three stages earlier.

Quick answer: put the pipeline's shape in Confluence as a Mermaid flowchart, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Text-based, editable, diffable — a pipeline diagram that changes when your pipeline changes. This post gives you three copy-paste examples: the linear stage view, quality gates with retry loops, and the deploy-to-tag gitGraph that records what actually shipped.

Your team grows by two people. The new hires open the wiki and find the architecture doc: a screenshot of a whiteboard, dated 14 months ago, where PaymentService does everything except the thing the diagram says OrderService does. Day-1 onboarding just taught two people the wrong architecture.

Quick answer: keep the architecture in Confluence as a Mermaid class diagram, rendered by Mermaid Plus Diagrams & AI Agent for Confluence and diffs like code. Classes, methods, interfaces, ownership — in editable text that updates when the code does. This post gives you three copy-paste examples: the onboarding service map, interface+implementation modules, and a request-flow sketch.

The meeting asks "who owns this feature?" and the answer is a Venn diagram by hand — drawn on a whiteboard, erased, redrawn, photographed, and lost. Two teams each built a piece of a shared workflow, and "the overlap" is exactly where the bugs and the SQL both landed. A decision framework is only useful while its picture survives the meeting; in Confluence as Mermaid text, it survives.

Quick answer: put decision frameworks in Confluence as Mermaid — venn-beta for set overlap, cynefin-beta for which operating mode a situation needs, quadrantChart for which item goes first — rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Each framework encodes a decision shape, and text keeps the picture attached to the decision record. This post gives you three copy-paste examples.

The bug report says "orders show twice in the report" and the fix takes three days because nobody on the team is sure whether order_lines links to orders on order_id or source_order_id, and both columns exist. The schema is documented — in a schema.md that lists columns as bullets and a diagram that was last exported when the DB was two migrations younger. The join question is exactly the thing an ER diagram answers at a glance, and the thing a bulleted column list cannot answer at all.

Quick answer: document the database schema in Confluence as a Mermaid erDiagram, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Entities hold keys and attributes; relationship lines carry the cardinality and the join's noun. When the discussion turns to the domain model the code exposes, add a classDiagram on the same page. This post gives you three copy-paste examples.

A root cause analysis is only as good as the disagreement it survives. When the 'root cause' box on your postmortem template contains one sentence, the meeting spends an hour relitigating that sentence. A fishbone diagram and a 5 Whys chain move the argument onto a diagram: everyone sees which categories were considered, which branch was chosen, and exactly how the 'why' answers arrive at a root cause.

Confluence is where RCA already happens — in the Root Cause Analysis template, in postmortems, in retros. The missing piece is a diagram that holds the reasoning. This guide shows you two copy-paste Mermaid diagrams: an ishikawa fishbone that maps every candidate cause category, and a flowchart 5-Whys drilldown that lands on one concrete fix.

Every incident has a story hidden inside a pile of timestamps: alert fired at 09:42, nobody acknowledged until 09:47, an engineer escalated at 09:54, a workaround landed at 10:20, services healthy at 10:31. Individually the timestamps mean nothing. Laid out on a timeline, they tell the story — and the story is what a postmortem is for.

Confluence is where incident postmortems already live. What Confluence does not give you is a native timeline. This guide shows you how to fill the Timeline section of an incident postmortem with a Mermaid diagram: one copy-paste timeline that visualizes detection → escalation → resolution, plus a sequence diagram that shows exactly how the failure propagated between services.

The support team knows where refunds leak. The product team knows where onboarding drops. The sales team knows where the pricing page confuses. Three silos, three versions of the customer's experience — and the roadmap meeting spends an hour reconciling them instead of deciding what to fix. What is missing is a single picture with a score on every step.

Quick answer: draw customer journeys in Confluence as Mermaid journey diagrams, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. A journey diagram puts every step in a row and every satisfaction score on one curve — the dips are visible, the actors are labeled, and the whole thing stays editable text. This post gives you three copy-paste examples: onboarding, a support ticket, and a checkout flow with a summary pie.

The sprint board on the wall shows 40 items in "In Progress" and the rulebook says "we limit WIP" and nobody agrees on what the limit is. The board is honest; the documentation is aspirational. A Kanban diagram in the wiki is the board as a spec — columns, limits, and the rework paths drawn so the workflow is a claim the team can argue with.

Quick answer: document the team's board in Confluence as a Mermaid kanban, rendered by Mermaid Plus Diagrams & AI Agent for Confluence. Columns as headings, work items as indented cards; the workflow rules (who may move what, when, including rework) as a stateDiagram on the same page. This post gives you three copy-paste examples.