Skip to content

Author, reviewer & approver guide

Maintained page — not a controlled document; kept current by the {{ROLE_DOCUMENT_CONTROLLER}}.

How controlled documents move from Draft to Approved at {{ORG_NAME}}. The lifecycle is defined normatively in the Document & Record Control Procedure (procedures/system/document-record-control-procedure.md); this page is the plain-language walkthrough. Three roles, three sections — read yours.

The one rule underneath everything: a document is Approved when — and only when — its named approver merges the pull request. No merge, no approval.

Authors (VS Code — no command line needed)

You edit in VS Code and use its Source Control panel; you never need a terminal.

  1. Open the repo in VS Code (once): Clone Git Repository → paste the repo URL → sign in to GitHub when prompted. [SCREENSHOT: VS Code clone dialog]
  2. Create a branch: click the branch name in the bottom-left corner → Create new branch → name it doc/<ID>-<short-slug>, e.g. doc/{{ORG_PREFIX}}-006-record-retention. [SCREENSHOT: branch picker]
  3. Edit the document. Update the body AND the frontmatter together: bump version, add a Revision History row, check the ownership section still matches. Leave status: Draft while you work.
  4. Commit: Source Control panel → type a one-line message → Commit → Sync Changes (this pushes your branch; CI runs automatically). [SCREENSHOT: source control commit box]
  5. Open the pull request: VS Code will offer Create Pull Request (or do it on GitHub). The PR template checklist appears — work through it, set status: Under Review, and request review from the document's named reviewer (the reviewer role in the frontmatter; the People register says who that is today).
  6. If your document has worker_consultation_required: true, consultation happens before approval — the consultation record goes in docs/records/consultation/ and gets linked in the PR.

CI failing? The error names the exact file and field — fix, commit, sync again. Ask the {{ROLE_DOCUMENT_CONTROLLER}} if it doesn't make sense.

Reviewers (GitHub web — nothing to install)

  1. You'll get a GitHub review-request email. Open the PR.
  2. Read the Files changed tab — the diff shows exactly what changed. [SCREENSHOT: files changed tab]
  3. Work through the PR checklist. Comment line-by-line where something needs work (Start a review → add comments → Submit review).
  4. Submit as Comment (feedback) or Approve (your review step is done). Your approval is the review step — the document is still not Approved until the approver merges.

Approvers (GitHub web)

  1. Confirm the named reviewer has approved and the checklist is complete — including the consultation record link when the flag requires it.
  2. Confirm CI is green.
  3. The final commit flips status: Approved and sets approved_date, and the Document Register row is updated in the same change (the author normally prepares this; check it's there).
  4. Merge. The merge is the approval event — it is timestamped, attributed to you, and permanent. Branch protection means nothing reaches main any other way. [SCREENSHOT: merge button]

After merge: if the document requires acknowledgement, the {{ROLE_DOCUMENT_CONTROLLER}} opens an acknowledgement campaign per the Document & Record Control Procedure.