Module 25 · Professional QA & test management

QA Documentation

By the Mutqan Soft QA team · · 18 min · Advanced

QA documentation is the written part of testing: the records that let others plan, review, repeat and take over the work. For example, a team releasing a delivery-tracking app every two weeks may keep a one-page test plan per release, regression test cases in a test management tool, defect reports in the tracker and a short completion report, each with a known reader and owner.

Building on the lesson on testware, this lesson decides which test work products deserve writing down, with ISO/IEC/IEEE 29119-3 as the map and lean documentation as the discipline.

Why it matters

Documentation costs effort twice: to write it and to keep it current. With too little, knowledge lives in one head, and when a client asks what was tested before a release, nobody can show it. With too much, documents go stale: a 40-page plan describing last year's scope misleads more than it helps.

The right documents make a tester's work reviewable, easy to hand over and defensible, because scope cuts and accepted risks are recorded with a name and a date.

What to write: reader, lifetime, owner, obligation

Before you create or keep a document, ask four questions. Who reads it, and what will they decide or do with it? Is it a one-off record, like one test run's log, or a living document that must stay current, like the regression suite? Who owns it? Does a contract, a regulator or the test policy require it, and in what form?

If nobody reads it to decide or act, do not write it. A required document follows the agreed template, a living one needs an owner and an update trigger, and a short-lived note can be a checklist. By purpose, teams usually write down:

  • Direction: why and how testing is done here (test policy, test practices or a strategy section in the plan).
  • Plans: scope, risks, schedule and when testing counts as finished.
  • Design and execution: test cases or charters, data and environment needs, run results.
  • Findings and reports: defect reports with evidence, progress and completion reports.
  • Decisions: scope cuts, waived exit criteria and accepted risks, with who decided and when.
  • Team knowledge: how to get test data, reset environments and run the suites; informal, but what new testers need first.
Before writing a QA document: no reader who decides or acts means do not write it, a fact another source holds gets a link, and only lasting or required items become owned documents.
Question 1: Will someone read it to decide or act?

  • Answer: No

    Outcome: Do not write itNobody will use it

  • Answer: Yes

    Question 2: Does another source already hold it?The story, the tracker, the test tool

    • Answer: Yes

      Outcome: Link to that sourceTwo copies drift apart

    • Answer: No

      Question 3: Must it stay current, or is it required by a contract, regulator or policy?

      • Answer: No

        Outcome: The lightest formA checklist or a short note

      • Answer: Yes

        Outcome: A document with an ownerRequired: the agreed form. Living: an update trigger

ISO/IEC/IEEE 29119-3: the document types at a glance

ISO/IEC/IEEE 29119-3:2021 gives templates and examples for the documentation produced by the test processes of ISO/IEC/IEEE 29119-2, and groups them in the three tiers listed below. The first edition of Part 3, from 2013, replaced IEEE 829-2008.

Three statements in it matter most. Documentation can be on paper or electronic, such as records in a test tool or a spreadsheet. Documents may be renamed, combined or split, and a team selects the set it needs; tailored conformance means recording that set and justifying what is left out. And it can be adopted in any lifecycle, including agile and DevOps. Treat it as a checklist of information, not an order to produce every template as a separate document.

  • Organisational: the test policy (why the organisation tests, objectives, training, ethics, how the value of testing is measured) and the organizational test practices (how testing is done across projects; the first edition called it the organizational test strategy).
  • Test management: the test plan (context and scope, stakeholders, risk register, the project's test strategy, activities and estimates, staffing and schedule); the test status report (the ISTQB test progress report); and the test completion report, or test summary report.
  • Dynamic test: the test model specification (what tests are derived from, such as requirements statements, partitions or a decision table; the 2021 edition replaced test conditions with test models, and a model can still include test conditions), test case and procedure specifications, test data and environment requirements and readiness reports, actual and test results, the test execution log and the incident report, also known as a defect or bug report.
ISO/IEC/IEEE 29119-3 arranges test documentation in three tiers: organisational (test policy, test practices), test management (plan, status and completion reports) and dynamic testing (specifications, logs, incident reports).

At the layer “Organisational test documentation”: Changes rarelyAt the layer “Dynamic test documentation”: Changes with each feature and test run

  1. 1Organisational test documentationWhole organisationTest policy · organizational test practices

    Why and how we test here

  2. 2Test management documentationOne project or productTest plan, with the test strategy inside · test status report · test completion report

    Plan the testing, then report its progress and completion

  3. 3Dynamic test documentationTest design and executionTest model, test case and test procedure specifications · test data and environment requirements and readiness reports · actual results and test results · test execution log · incident report

    Incident report: also called a defect or bug report

Names and contents can be tailored, and an item can be a record in a test tool rather than a separate document.

Lean documentation: just enough, just in time

The Manifesto for Agile Software Development values "working software over comprehensive documentation" while granting that documentation has value. Lean test documentation applies that balance: write what a reader needs, when needed, in the lightest form that works, and nothing a better source already holds.

Lean does not mean nothing written: contracts, regulators, audits, distributed teams and long-lived products justify more formality. Record the level you chose in the test strategy.

  • Link, do not copy: the plan links to the acceptance criteria in the story; copies drift apart.
  • One home per fact: risks in the register, defects in the tracker, results in the test tool; reports point to them.
  • Lightest form that works: checklists for stable areas, charters and session notes for new features, scripted cases where exact steps and data matter, such as payments.
  • Readable automated tests that run on every build document current behaviour and fail when it changes, so they do not go stale silently.
  • Update when a decision changes, not by the calendar; archive documents nobody owns.

Worked example: trimming a documentation set

A new QA lead joins FleetTrack, a fictional delivery-tracking product with six developers and two testers. She inherits a 45-page master test plan last updated eight months ago, 1,200 spreadsheet test cases (many for removed screens), a status report that takes half a day each week, and no guide to test data. One constraint is fixed: the client's contract requires a signed completion report per release, showing which requirements were tested.

She maps readers and needs to 29119-3 items and agrees the map below with the product owner and the development lead:

  • The plan's long-lived parts (levels, types, tools, defect workflow, standard exit criteria) moved to a practices page that rarely changes; release plans keep only scope, risks, schedule and their own criteria.
  • Cases for removed screens were retired, duplicates merged and the regression set moved to the test tool; stable low-risk areas became checklists.
  • The status report became a dashboard plus a five-line note: headline, blockers, decisions needed.
  • The completion report stays formal because the contract requires it: written in Markdown, exported to PDF for signature, and traced through requirement IDs on the test cases instead of a hand-kept matrix.
  • Not written: a separate test policy (a short purpose statement opens the practices page, which the standard allows), procedure specifications (the steps live in the cases and automation) and readiness reports (the plan's entry criteria cover them).
FleetTrack documentation map (fictional), agreed in sprint 31

Item (29119-3 name)        Form and place                 Owner    Update trigger
Org. test practices        wiki page, about 4 pages       QA lead  quarterly review
Test plan (with strategy)  1 page per release, wiki       QA lead  scope, dates, risks
Test models, test cases    regression set in test tool;   testers  feature changes
                           charters for new features
Test data and environment  how-to page: accounts, seed    testers  environment changes
  requirements             scripts, reset steps
Execution log, results     test tool runs, CI report      tool     every run
Incident reports           defect tracker                 finder   until closed
Test status report         dashboard + 5-line note        QA lead  weekly
Test completion report     2 pages, signed PDF            QA lead  each release

Not written: a separate test policy (a purpose statement opens the practices page),
separate test procedure specifications and readiness reports,
and a traceability matrix kept by hand

Try it: Requirements → Test Cases Try it: Markdown Formatter Try it: Markdown to PDF

Common mistakes

  • Filling every template section because it exists, so boilerplate hides the lines that matter.
  • Copying requirements or steps into several documents until nobody knows which copy is right.
  • Writing a plan at kick-off that nobody owns or updates.
  • Reading "lean" as "nothing written": decisions, accepted risks and reproduction steps must always be recorded.
  • Scripting every step for stable areas a checklist would cover, so maintenance outweighs the value.
  • Treating ISO/IEC/IEEE 29119-3 as a list of mandatory documents rather than a checklist you can tailor.

The QA perspective

Review the documentation set when you join a team and at each retrospective: what did someone need and not find, and what did nobody read? Agree it with the product owner and the development lead, plus compliance or the client where involved.

When asked for "the documentation", ask who it is for: an auditor needs evidence that requirements were tested and risks accepted by someone authorised, a developer needs a reproducible defect report. Write for that reader and date every living page.

Practice exercise

Design a lean documentation set for a new contract

Your task

You are the only tester in a team of four developers and a product owner building a meal-ordering web app. Stories carry acceptance criteria and an automated API suite runs in CI; nothing else is written. A new hospital-group contract requires a completion report per release showing which requirements were tested.

Propose the documentation set: for each item, its 29119-3 name, form and place, owner and update trigger. Then say what you will not write, and why.

Steps
  1. List the readers and what each needs.
  2. Map each need to a 29119-3 item; check whether a source already holds it.
  3. Choose the lightest form and place, linking instead of copying.
  4. Give living items an owner and an update trigger; list what you will not write.
Show the model answer
Model answer

Readers: the team, the product owner, the hospital group (the completion report and the requirements tested) and future testers.

Test plan with strategy: one wiki page per release (scope, top risks, levels and types including the API suite, entry and exit criteria, environments), owned by you and updated when scope, dates or risks change.

Test models and cases: the acceptance criteria serve as the test model (requirements statements are one of the standard's examples) and are linked, not copied. Write cases only for regression and high-risk flows, such as cancelling an order; use charters for new stories.

A how-to page for test data and environments; logs and results from the test tool and CI; incident reports in the tracker; status through the sprint review and a dashboard. The completion report is formal, owned by you, written for each release and traced through story IDs on the tests.

Not written: a separate test policy and organizational test practices (one team, so the plan's strategy covers them), procedure specifications, readiness reports and a hand-kept traceability matrix; record these choices and the reasons in the plan.

Frequently asked questions

Is ISO/IEC/IEEE 29119-3 mandatory?

Only when a contract, a regulator or your organisation requires conformance. The standard itself allows tailored conformance, electronic records and adapted names and contents, so many teams use its templates as a checklist rather than as forms to fill in.

Do agile teams still need a test plan?

They need the planning information (scope, risks, approach and criteria), not necessarily a long document. Much of it lives in the backlog and the Definition of Done, and the rest fits on one page per sprint or release. ISO/IEC/IEEE 29119-3 states that it can be adopted in agile and DevOps lifecycles, and that teams organised around products can read "product" where it says "project".

Are automated tests documentation?

Partly. A readable test that runs on every build documents what the system does today and fails when that changes. It does not record why the behaviour is required, what was deliberately left untested or which risks were accepted; those still need a few written lines.

References

Tools

Practise with Mutqan tools

Requirements → Test Cases

Convert a list of numbered requirements into traceable test cases with a requirement-to-test matrix.

Test Design

Risk-Based Test Generator

Score features by likelihood and impact, then generate a prioritised risk-based test plan.

Test Design

Test Case Generator

Generate structured test cases (id, title, preconditions, steps, expected result, priority) from a feature description and field list.

Test Design

Markdown Formatter

Normalise Markdown formatting (headings, lists, tables, emphasis) and preview the rendered result.

Formatting

Markdown to PDF

Convert Markdown (.md) files to PDF in your browser: headings, lists, tables, code blocks, quotes, links and images typeset with embedded fonts.

PDF Conversion

Go deeper

Your progress on this topic

Part of the QA Roadmap