Skip to main content

Create a controlled document

Author a new SOP or policy directly in Better Comply using the Markdown editor, then move it through the lifecycle. A document you create starts in Draft and is not visible to learners until it is approved and made effective.

Who this is for

Administrators (Quality Admin, HR Admin, Corporate Admin). Creating a controlled document is an admin-only action.

Create the document​

  1. Open Controlled Documents and start a new content document.
  2. Choose the scope:
    • Corporate makes the document available across the organization.
    • Departmental scopes it to one department. You must then pick the department.
  3. Pick a category (for example a policy or SOP category from your configured list).
  4. Enter a title, and optionally a short description.
  5. Write the body in the Markdown editor. The toolbar gives you headings, bold, italic, lists, links, and a tabbed preview so you can check rendering without leaving the page.
  6. Select Create.
Screenshot pendingCreate controlled document page with scope, category, title, and the Markdown editor

The document is created in Draft with version 1.0, and you are taken to its detail page. To release it, follow Lifecycle and approval.

Why the editor, not a plain text box

The Markdown editor sanitizes pasted and typed content and produces a clean, auditable body. Content documents are always written through this editor so the stored body round-trips through the same safe rendering the reader sees.

What happens behind the scenes​

When you create a content document, the body is written on the server, not from your browser. The server writes the document record, stores the Markdown, creates the initial version, and records a create_controlled_document event in the audit trail.

Creation is server-side and audited

The save is performed by Better Comply's backend so it can record a fail-loud audit event. If that audit record cannot be written, the entire creation is rolled back: the document, its version, and the stored body are all removed. A controlled document is never left in the system without a matching audit trail entry. See the Compliance area for the audit model.

Upload a file instead of authoring​

If you start from an existing file rather than writing the body yourself, the Upload controlled document dialog opens with a choice up front:

  • Keep as file stores the original binary as the controlled document and indexes it for AI search. The document is read and downloaded as the original file.
  • Convert to Markdown creates an editable Markdown controlled document from the file. The original upload is kept as provenance and stays downloadable.

Accepted formats are PDF, DOCX, TXT, HTML, and legacy DOC.

Legacy .doc is convert-only

Legacy .doc files cannot be stored as a raw indexable file, so when you pick a .doc the dialog automatically selects Convert to Markdown and disables Keep as file. The conversion handles the normalisation for you.

To convert and edit the Markdown before committing, see Import a Word or PDF.

Set the document code​

The document code (for example SOP-QA-001) is the human-readable identifier your physical SOPs and external references use. It is separate from the internal identifier that the audit trail cites.

  1. On the document's detail page, open the Properties tab.
  2. If no code is set, select Set document code.
  3. Enter the code (up to 64 characters) and save.

Once set, the code appears as the first chip in the document's metadata strip on the detail and viewer pages, and as a prefix on the title in the document list. To change or clear it, reopen the same dialog.

Screenshot pendingProperties tab with the Set document code dialog

Edit a draft or effective document​

You can edit a content document's body while it is in Draft or Effective. Editing is blocked while a document is In review, Approved, Superseded, or Obsolete, because changing the body in those states would bypass the approval workflow.

  1. Open the document and select Edit.
  2. Make your changes in the Markdown editor.
  3. Enter a change reason of at least 10 characters. This is required: ISO 9001 expects a documented justification for every change to a controlled document.
  4. Save.

Saving creates the next version (for example v1.1) rather than overwriting the current one. Like creation, the edit is performed server-side and recorded as an edit_document_content audit event, and it is rolled back if that audit cannot be written. Each version keeps its own stored body, so older versions stay readable and downloadable. See Versions and history.

Editing is server-side and audited

Content edits never write directly from the browser. The change reason, the new version, and the stored body are committed by the backend with a fail-loud audit event that reverts the change on failure.

Translate a content document with AI​

On the edit page for a content document, choose a target language and select Translate with AI. Better Comply translates the current Markdown body and loads the result back into the editor.

The translation is editable before it is saved. Review the text, adjust any controlled terminology, and confirm the change reason. Saving creates a translated version variant linked to the source version through the same audited server-side edit flow described above. It does not replace the document's current effective source version; readers can choose the translated language in the document viewer when that variant exists.