Knowledge document template

Search returns passages from your document rather than the document as a whole. Any passage may be used without its surrounding context, so include the details needed to interpret each one. That single constraint shapes the template below: write each section so it makes sense on its own, and repeat the small amount of context that changes how a fact should be read.

Why not put the details at the top

It is tempting to open a document with a block of Applies to, Effective from, and Source lines and consider the whole file labeled. However, a question about a rule later in the document may retrieve a passage that does not include those lines. Do not rely on a filename, document property, or folder name to supply context for every passage.

Scope written inside a document is there to be read, not enforced. It does not restrict who can retrieve the document. Set the persona’s knowledge scope by choosing which folders its tools search.

The template

Replace the placeholders, drop the sections that do not apply, and include only what your source supports.

# [Topic] — [audience, region, product or version]

## What this covers

[This document covers X for Y. It does not cover Z.]
[Source: original title, version, section. Effective from date.]

## [First fact or rule]

[State the fact with its subject named in full: which plan, region, product
or version it applies to. Keep units, conditions and exclusions in the same
paragraph, or in the same table row.]

[Source: original title, version, section. Effective from date.]

## [Eligibility or decision criteria]

[What must be known before this rule applies, and what the source says to do
in each case. Name the subject again — do not write "as described above".]

[Source: original title, version, section.]

## [Procedure]

[Prerequisites, ordered steps and completion checks, as documented. Name the
product and version the procedure applies to.]

[Source: original title, version, section.]

Two habits matter more than the exact headings:

Name the subject in every section. “The Business plan includes priority support” survives retrieval; “This includes priority support” does not.
Keep the exception with the rule. A restriction in a separate “Important information” section will be retrieved separately, or not at all.

A worked example

The difference is small to write and large in effect. Both versions are fictional.

# Returns policy

Applies to: Region A, online purchases
Effective from: 1 March 2026
Source: Returns Policy v4.2

## Return window

Returns are accepted within 30 days.

## Exclusions

Personalized items are excluded.

# Returns policy — Region A online purchases

## Return window

For online purchases in Region A, unused items can be returned within 30 days
of delivery. Personalized items are excluded.

Source: Returns Policy v4.2, section 2.1. Effective from 1 March 2026.

In the first version, a question about the return deadline retrieves “Returns are accepted within 30 days” — with no region, no exclusion, and no date. In the second, the same question returns a passage that answers it correctly on its own.

Record what you do not know

Where a fact is unconfirmed, say so beside the fact rather than in a footnote or a separate section:

## Return window — UK purchases

The return period for UK purchases is awaiting confirmation: the two source
policies give different deadlines (14 days in Returns Policy v4.2, 30 days in
the UK Customer Handbook v2). Do not state a deadline until the policy owner
resolves this.

Don’t fill an unknown date, value, or procedure step with a guess. A passage that admits a gap is far better than one that invents an answer.

Before you upload

Save the completed document as a .md file. Keep this template, and any editing notes about it, out of your persona’s reference folders — otherwise the persona will retrieve advice about writing documents when a user asks about your policies. Then check a real passage rather than trusting the structure: upload the file and search for a fact from the middle of it. If the returned text does not name its subject, scope, and source, the section it came from needs more context, not the document.

Next steps

Use Prepare documents for worked examples of splitting files, removing duplication, and handling conflicting sources, then follow the upload checklist.

Introduction

Personas

Avatar videos

Security & Compliance

Resources

Knowledge document template

Why not put the details at the top

The template

A worked example

Record what you do not know

Before you upload

Next steps

​Why not put the details at the top

​The template

​A worked example

​Record what you do not know

​Before you upload

​Next steps

Why not put the details at the top

The template

A worked example

Record what you do not know

Before you upload

Next steps