SELF-GUIDED BA PRACTICE Packages available · Access after confirmed paymentSee packages ↗

Agile & Tools

Confluence documentation for business analysts

Agile & Tools · Published · Updated · 9 min read · By BA Mentorship Editorial

Part of our guide to business analyst tools.

What Confluence is, in plain English

Confluence is a team documentation tool from Atlassian. Imagine a shared company notebook where every page can be searched, commented on, linked to other pages and edited by several people. Pages live inside spaces, which are like folders for a team or project, and pages can be nested into a tree. The vendor's own Confluence guides show the product features. A Confluence page is just a document with a history: you can see who changed what and go back to an earlier version.

It is often paired with Jira. Jira holds the small pieces of work (tickets); Confluence holds the explanations that are too long for a ticket (the "why", the rules, the diagrams). A ticket links to the page, and the page links to the tickets. Other companies use different tools, such as SharePoint, Notion or a wiki, and the same principles apply. In the BA Lab, stage 9 is a Confluence-style documentation space: a simulation for practice, not Confluence itself.

Why a business analyst needs good documentation

Projects forget things. People leave, memories fade, and a decision made in a meeting in March is argued about again in July. Documentation is the project's memory. A business analyst is usually the person who keeps it, because they are the one who hears the needs, the rules and the reasons. Good documentation:

  • Lets a new developer, tester or analyst get productive in days instead of weeks.
  • Prevents repeated arguments by recording what was decided, by whom and why.
  • Provides evidence for audits and sign-off (see sign-off).
  • Keeps tickets short, because the detail lives in one linked place.
  • Supports testing, training and support after go-live.

Bad documentation is worse than none: it is out of date, nobody owns it and people stop trusting it. The goal is not volume; it is documentation that is current and findable.

A simple space structure that works

Imagine CareBridge Clinics, a fictional group of clinics building an online appointment system. A BA sets up the project space like this:

CareBridge Online Booking (space)
  1. Project home (goal, team, status, key links)
  2. Business case and scope
  3. Stakeholders and communication plan
  4. Requirements
       4.1 Requirements overview (list with IDs)
       4.2 Feature pages (one per feature)
       4.3 Non-functional requirements
  5. Process models (as-is, to-be)
  6. Data and integrations
  7. Decisions (decision log)
  8. Meetings (minutes by date)
  9. Test and release (UAT plan, traceability, release notes)
  10. Glossary and open questions

The numbers make the order obvious, and a short project home page that links to everything is the most valuable page you will write. Keep names plain and consistent, for example "Feature: Reschedule appointment", so search results make sense. Add labels (tags) such as requirement, decision or draft to help filters. If you work from the lab stages, the order maps naturally: business case, stakeholders, elicitation, requirements, process, data, APIs, delivery, documentation, dashboards and UAT.

A requirements page that people can use

Layout of a skimmable feature pageA dashboard layout. Header block: Owner, status, last reviewed, related tickets. Purpose: Two sentences: problem and outcome.. Scope: In and out. Users: Who can do what. Business rules: Numbered, one rule per line: BR-01, BR-02, BR-03. Process, screens: Diagram links. Data and APIs: Fields, sources. Acceptance: Criteria or ticket links. Open questions: Owner and due date; then change history.Header blockOwner, status, last reviewed, related ticketsPurposeTwo sentences: problem and outcome.ScopeIn and outUsersWho can do whatBusiness rulesNumbered, one rule per line: BR-01, BR-02, BR-03Process, screensDiagram linksData and APIsFields, sourcesAcceptanceCriteria or ticketlinksOpen questionsOwner and due date;then change history
A feature page a busy reader can skim. Status and owner first, numbered rules in the middle, open questions and change history at the end.
Diagram in words
  • Header block: Owner, status, last reviewed, related tickets
  • Purpose: Two sentences: problem and outcome.
  • Scope: In and out
  • Users: Who can do what
  • Business rules: Numbered, one rule per line: BR-01, BR-02, BR-03
  • Process, screens: Diagram links
  • Data and APIs: Fields, sources
  • Acceptance: Criteria or ticket links
  • Open questions: Owner and due date; then change history

A feature page should be skimmable and complete. A useful template:

  1. Header block: owner, status (Draft, In review, Approved), last reviewed date, related tickets.
  2. Purpose: two sentences on the problem and the outcome.
  3. Scope: what is in, what is out.
  4. Users and permissions: who can do what.
  5. Business rules: numbered, one rule per line.
  6. Process or screens: diagram or wireframe links.
  7. Data and integrations: fields, sources, APIs.
  8. Acceptance criteria or a link to the tickets that hold them.
  9. Open questions with owner and due date.
  10. Change history: date, what changed, why.

Here is a short sample for CareBridge:

IDBusiness ruleSource
BR-01A patient may reschedule an appointment up to 24 hours before the start time without penalty.Clinic operations policy (owner: Dr. Mehta, fictional)
BR-02Within 24 hours, the patient is asked to call the clinic instead of rescheduling online.Workshop 12 Nov
BR-03Rescheduling releases the original slot immediately.Front-desk interview

The IDs matter: tickets, tests and the traceability matrix can refer to BR-01 without ambiguity. For bigger documents such as a BRD, see BRD vs FRD vs SRS; the free page on a business requirements document example shows a filled sample.

The decision log and meeting minutes

A decision log is a table of important decisions. It is the cheapest, most useful page in any project because it stops the same conversation being repeated.

IDDateDecisionReasonDecided byImpact
D-072026-11-12Online rescheduling closes 24 hours before the appointmentClinics could not refill late-cancelled slotsOperations leadRule BR-01, tickets CB-31 and CB-32
D-082026-11-19SMS reminders are in release 2, not release 1Supplier contract not signedSponsorScope reduced; epic CB-40 moved

Meeting minutes should be short and action-oriented. Use this shape: date, attendees, purpose, decisions made, actions (owner and due date), open questions. Send them the same day while memory is fresh. A good minute reads like:

Workshop: rescheduling rules, 12 Nov. Attendees: operations lead, two front-desk staff, IT lead, BA. Decisions: D-07. Actions: BA to update BR-01 by 14 Nov; IT lead to confirm slot release timing by 16 Nov. Open: Do walk-in patients count as appointments for the rule?

Link every decision to the requirement and the tickets it changes. The log then doubles as evidence when someone later asks "why does it work this way?".

Meeting minutes

Workshop: rescheduling rules, 12 Nov.1

Attendees: operations lead, two front-desk staff, IT lead, BA.2

Decisions: D-07.3

Actions: BA to update BR-01 by 14 Nov; IT lead to confirm slot release timing by 16 Nov.4

Open: Do walk-in patients count as appointments for the rule?5

  1. Purpose and date. What the meeting was for, so the page can be found later.
  2. Attendees. Who was in the room, by role.
  3. Decisions. By ID, so the reason lives once in the decision log.
  4. Actions. Each one with an owner and a due date.
  5. Open questions. Written down, so they are answered rather than forgotten.
Minutes that someone who was not there can act on. Short, linked to the decision log, and every action has an owner and a date.

Writing style: how to make pages that get read

  • Lead with the answer. The first lines should tell a busy reader what the page is and its status.
  • Use short sentences and plain words. Say "must" for rules and "should" or "may" for options, and define them once. Avoid vague words like "fast", "easy" and "appropriate"; give numbers.
  • Prefer tables and numbered lists for rules and options; use diagrams for flows.
  • One page, one purpose. If a page answers three questions, split it.
  • Define terms once in a glossary page and link to it.
  • Show dates and owners. A page without an owner is already decaying.
  • Link instead of copying: one source of truth per fact.
  • Use comments for questions and resolve them when answered, then move the answer into the text.

Ask a colleague who did not attend the meeting to read the page cold. Where they hesitate, rewrite.

Versions, approval and who may edit

Living documents need rules, otherwise they change under people's feet. Decide three things at the start.

Who may edit? A common pattern is that the whole project team can comment, the BA and named owners can edit, and only an approver can change a status to Approved. Restricting editing on approved pages protects the baseline that testers and auditors rely on.

How is approval recorded? Write the approver's name, the date and the version in the header block, and keep the approval message or meeting reference. If your organisation requires formal sign-off, store the evidence in the place the policy names rather than in a private mailbox. Never invent an approval that did not happen.

How are changes handled after approval? Treat a change to an approved requirement as a small change request: record what changes, why, the impact on scope, cost and tests, and who agreed. Add a row to the change history on the page and update the linked tickets and test cases. The page history shows every edit, but a human-readable note explains the reason, which the history does not.

Finally, keep personal data out. Use fictional or masked examples in screenshots and sample tables. If your work involves health, finance or other sensitive information, follow your organisation's rules on where such content may be stored and who may see it.

Step by step: setting up documentation on day one

  1. Create the space and a project home page with goal, team, links and a status line.
  2. Add the skeleton pages from the structure above, even if they are only headings.
  3. Create templates for feature pages, meeting minutes and decisions so everyone writes in the same shape.
  4. Agree ownership and review: who may approve a requirement page, and how often is each page reviewed?
  5. Set up the Jira links so tickets show the pages that explain them.
  6. Update the log and minutes within a day of each meeting.
  7. Do a short weekly tidy: archive dead pages, update statuses, close resolved questions.
  8. Before release, confirm the final pages are marked Approved and match what was built, because support and training will use them.

See Jira for business analysts for the ticket side of this partnership.

Common mistakes

  • ✅ Keep one project home page that links everything. ⚠️ Fifty orphan pages that only the author can find.
  • ✅ Show status and last reviewed date on every page. ⚠️ Silent, stale pages that people still follow.
  • ✅ Number requirements and decisions. ⚠️ Referring to "the thing we agreed on Tuesday".
  • ✅ Record the reason for each decision. ⚠️ Recording only the outcome, so the debate restarts.
  • ✅ Write for a reader who was not in the room. ⚠️ Notes full of private shorthand.
  • ✅ Keep sensitive data out of pages. ⚠️ Pasting real customer details or passwords into documentation.
  • ✅ Archive obsolete pages. ⚠️ Leaving two contradictory versions both searchable.

Reader exercise

Take a meeting you attended recently, even a family or club meeting. Write minutes using the shape above (date, attendees, decisions, actions with owners and dates, open questions). Then create two decision log rows with reasons. Finally, write a mini feature page with a purpose line, three numbered business rules and two open questions. Ask someone who was not there to find the next action from your notes alone in under a minute.

How to practise in the BA Lab

Stage 9 of the BA Lab is a Confluence-style space in a fictional project: you create requirement pages, a decision log and meeting minutes from the information in your project, and the checks flag missing owners, vague wording and unanswered questions. It is a simulation for building the habit, not Confluence. Your finished pages can become portfolio samples; see building a BA portfolio without experience. The pricing page lists the packages that include this stage.

Silent clip, about 19 seconds A Jira-style story, then a Confluence-style requirements page built from a template, with checklist warnings, in the BA Lab. Simulations, not Atlassian products. Recorded with a synthetic test account.

Frequently asked questions

What should a business analyst document in Confluence?

Business case and scope, stakeholders, requirements with IDs and owners, process models, data and integration notes, the decision log, meeting minutes, UAT and release information, and a glossary.

How is Confluence different from Jira?

Jira tracks individual pieces of work as tickets. Confluence holds longer explanations such as requirements, decisions and notes. Teams link the two so each ticket points to its explanation.

Do I need Confluence to be a business analyst?

No. Some companies use SharePoint, Notion, wikis or shared drives. The skills of structure, plain writing, ownership and decision tracking are tool-independent.

How do I keep documentation up to date?

Give every page an owner and a review date, update minutes and decisions within a day, link to one source of truth instead of copying, and archive pages that are no longer valid.

What is a decision log?

A table that records important decisions with date, reason, decision maker and impact, so the team does not reopen settled questions and can explain why the solution works as it does.

This article is educational. All companies, people and numbers in the examples are fictional. BA Mentorship does not issue professional certifications and cannot guarantee any job or interview outcome.

Key terms in this article

Browse the full glossary

CHECK BEFORE CONTINUING

Keep your work safe