Need AI Training/Help?CloudYeti.io/meet
MarkdownMe
Confluence wiki markup guide

Confluence Technical Spec Template

Format a Markdown technical spec for Confluence with problem, decision, architecture, tradeoffs, and open questions.

Direct answer

A useful Confluence technical spec starts with the problem, goals, non-goals, proposed approach, decision table, rollout plan, risks, and open questions, then converts Markdown headings, tables, links, and code identifiers into Confluence wiki markup.

Open Markdown to Confluence converter

When to use this

  • A design proposal or architecture note starts in Markdown.
  • The team reviews technical specs in Confluence.
  • The spec includes tradeoff tables, rollout notes, or code identifiers.

Steps

  1. Write the problem and goals before the solution.
  2. Separate goals from non-goals.
  3. Use a decision table for options, pros, cons, and decision.
  4. Add rollout, risks, and open questions.
  5. Convert the Markdown into Confluence wiki markup before pasting.

Example conversion

Markdown input
## Export reliability spec

### Problem

Large workspace exports time out before the browser download starts.

### Goals

- Generate exports asynchronously
- Keep download links available for 24 hours
- Track `export_ready` and `export_failed`

### Options

| Option | Pros | Cons |
| --- | --- | --- |
| Synchronous export | simple | timeout risk |
| Background job | reliable | queue required |

> Note: First release supports CSV only.
Confluence wiki output
h2. Export reliability spec

h3. Problem

Large workspace exports time out before the browser download starts.

h3. Goals

* Generate exports asynchronously
* Keep download links available for 24 hours
* Track {{export_ready}} and {{export_failed}}

h3. Options

|| Option || Pros || Cons ||
| Synchronous export | simple | timeout risk |
| Background job | reliable | queue required |

{note}
First release supports CSV only.
{note}

Common mistakes

  • Do not start with implementation details before defining the problem.
  • Do not bury tradeoffs in prose if a table would make the decision easier to review.
  • Do not omit non-goals when the spec could otherwise expand during review.

FAQ

What should be in a Confluence technical spec?
Include problem, goals, non-goals, proposed approach, tradeoffs, rollout plan, risks, open questions, and links to related tickets or diagrams.
Can Markdown tables be converted to Confluence tables?
Yes. Markdown pipe tables can become Confluence wiki tables with double-pipe header cells and single-pipe body rows.
Should code identifiers be inline code in a Confluence spec?
Yes. Inline code keeps event names, API fields, flags, and config keys visually distinct after conversion.

Related Confluence guides

Markdown Runbook to Confluence

Convert a Markdown runbook into Confluence wiki markup with steps, warnings, code blocks, and rollback notes.

Markdown Incident Review to Confluence

Convert a Markdown incident review into a Confluence page with timeline, impact, root cause, and follow-up actions.

Markdown Meeting Notes to Confluence

Turn Markdown meeting notes into a Confluence page with decisions, action items, blockers, and links.