What are Requirements and Reference Docs?

Almost everything Qrtr tells you about a document traces back to two small piles of files attached to the project. Get those right and the results are useful. Get them wrong and you will spend your time arguing with the score instead of improving the work. This article explains the difference between the two kinds, how Qrtr uses each, and what makes a good one.

The distinction in one line each

A requirement document defines what your deliverable has to do. Qrtr's own explanation lists the usual candidates: proposals, statements of work, engagement letters, audit protocols and terms of reference. These are the documents that create obligations — the things a client, a regulator or your own methodology says the output must contain, address or avoid.

A reference document is supporting material you work from and cite: internal or external standards, policies, guidelines. Qrtr's role here is different. Rather than treating a reference as a list of obligations, it checks that where you have relied on or cited that material, you have used it correctly.

The short version: requirements are what you promised, references are what you cite while delivering it.

Where they are attached

Both are attached to the project's quality profile, and you can add them at three moments.

During project creation, step two of the wizard has separate upload zones for Requirement Documents and Reference Documents, each with an explanatory panel. Both are marked optional, though a project with no requirement documents gives a check very little to measure against.

On an existing project, choose Edit quality profile and use Add another document under Requirements or Add document under References. Each attached file shows its size with icons to preview, download or remove it.

On a quality profile template, the same two sections exist, so a standard set of requirement and reference material can be attached once and applied to every project created from that template. For any recurring engagement type, this is the right place to do it.

Accepted formats are PDF, DOCX and TXT, up to 10MB each.

YOUR ACTION ▶ PASTE IMAGE 17.1 HERE

The two upload zones

Step two of the new project wizard showing both upload zones and both explanatory panels in one image, with the accepted formats and size limit legible. This is the clearest statement of the distinction anywhere in the product.

Delete this whole box once the image is in place.

YOUR ACTION ▶ PASTE IMAGE 17.2 HERE

Documents on an existing profile

The Documents block of a project quality profile with a requirement document attached, showing the file size and the preview, download and remove icons, plus the empty References section beneath.

Delete this whole box once the image is in place.

What Qrtr does with a requirement document

Qrtr reads the requirement documents and derives a set of individual, checkable requirements from them. Every finding in a report points back to one or more of these, and Show requirement on any issue opens the source so you can read the original wording rather than the summary.

Each requirement resolves one of three ways. It is met, and appears as a closed item confirming the document addresses it. It is not met, and becomes an issue with a severity. Or Qrtr cannot find the relevant content at all, in which case the issue carries a Missing anchor and the note that the requirement could not be located.

Two patterns are worth recognising because they surprise people. Required content excluded appears when the document explicitly says it has not done something the requirements ask for — a draft that states its recommendation is still to be confirmed will be flagged for exactly that, correctly. And Prohibited content found appears when the document includes something the engagement excluded; if your scope says detailed design is out of scope and the report proposes detailed design, that is a finding, not a bug.

That second pattern is the strongest argument for attaching scope documents rather than just requirement lists. Exclusions are requirements too, and Qrtr can only enforce them if you give them to it.

YOUR ACTION ▶ PASTE IMAGE 17.3 HERE

A finding traced to its requirement

An issue card with Show requirement expanded to list the source requirements it derives from. Ideally use an example with the requirement text visible so readers see the chain from source document to finding.

Delete this whole box once the image is in place.

What Qrtr does with a reference document

References are not turned into a checklist of things the document must contain. They are the material against which your use of them is judged. Where the document cites a standard, clause or policy, Qrtr checks the citation is used correctly and consistently.

The practical consequence is that references should be the actual authoritative material — the standard, the policy, the guideline — not a summary of it, and not a document that is really a set of obligations in disguise. If a file is telling you what the deliverable must contain, it belongs in requirements.

What makes a good requirements document

Specific obligations beat general aspiration. A sentence saying the report will identify a single preferred option produces a checkable requirement; a sentence saying the report will be of high quality does not.

Include the scope boundaries in both directions. What is in, and just as importantly what is excluded, since exclusions are enforceable.

Include the deliverable definition — what the output is, what form it takes, who it is for.

Strip the parts that are not obligations. Fee schedules, marketing language and boilerplate add noise and generate requirements nobody intended.

Attach the version that actually governs the work. A superseded scope produces findings that are technically correct and practically useless.

Changing the documents later

Adding or removing a requirement or reference document changes the quality profile, which creates a new version. The change appears in Change history with a tag noting a document change, who made it and when, and every output records the profile version it ran against.

This matters when comparing results. A document that scored badly under v3 and well under v5 may not have improved at all — the standard may have changed. When you do change the attached documents, re-run the check so you are comparing like with like.

YOUR ACTION ▶ PASTE IMAGE 17.4 HERE

Change history showing a document change

The expanded Change history list with at least one entry recording an added or removed requirement document, showing the version number, the tag, the actor and the date.

Delete this whole box once the image is in place.

When results do not look right

Before concluding the check is wrong, work through the attachments.

If scores are uniformly low across good documents, the requirements are probably too numerous, too granular, or drawn from the wrong source file. If a specific finding looks wrong, open Show requirement and read the original wording — most disputed findings turn out to be accurate readings of a poorly worded requirement, which is fixable at source. If findings are dominated by Missing anchors, the requirement document may be describing a different deliverable than the one being checked. And if a reference keeps producing citation findings, check that it is the same edition the document cites.

Fixing the requirement document once is worth more than dismissing the same finding on every future check.

DECISION NEEDED ▶ NOT ARTICLE COPY ▶ DELETE BEFORE PUBLISHING

Three things to confirm with the product team. How much of a requirement document is turned into requirements — everything, or only sentences that read as obligations — because that determines the advice about stripping boilerplate. How a reference is matched to a citation, and whether a document has to name the reference explicitly for the check to apply. And what happens to historical results when a requirement document is removed: whether past reports keep their findings or lose the link to the source.

Understanding your quality profile
How to edit a requirements document
How to set up and edit a project
How to read your Qrtr Check report
Statuses and terminology: a glossary
Your first week with Qrtr: a setup guide for administrators