Writing knowledge for Aiva

Aiva answers from the knowledge you give her. The way it is written decides how reliably the right part of it is found for each visitor question, and how precisely Aiva can answer from it. This page is the writing standard that pays off.

How Aiva reads your knowledge

Each source you add is split into sections. When a visitor asks a question, the few sections that best match the question are retrieved from everything you have enabled, and Aiva answers only from what was retrieved.

Each section competes alone. Aiva does not see the whole document around a retrieved section, so a section that only makes sense in context can be found and still fail to answer. Everything below follows from that one fact.

Write self-contained sections

Every section should be fully understandable on its own: no pronouns that refer to an earlier section, no "as described above", and no answer that only exists behind a link. Name the product or feature in the text instead of leaning on a pronoun, and spell out abbreviations at least once per section.

Before:

## Renewing it
 
As explained above, it stays active until the end of the term.
Renewing extends this by the same duration.

After:

## Renewing a license
 
A license key stays active until the end of its purchased term.
Renewing a license key extends it by the same duration, for example
a one year key renews for one more year.

Headings in the customer's words

Start each section with a heading worded the way customers actually ask. A heading like "How do I activate my license key?" is found for the question "how do I activate my key", while a heading like "Activation" contributes much less.

Phrase the heading as the general question, not one customer's specific case. "How do I get a refund?" covers every way a refund request is worded. "I paid twice and want one payment back" covers one.

Answer in full sentences that restate the question

A heading and a bare "No." fail together when the section is read alone. Carry the question's words into the answer, so the answer stands even out of context.

Before:

## Do I need the original payment card for a refund?
 
No.

After:

## Do I need the original payment card for a refund?
 
No, a refund does not require the original payment card. The refund
goes back to the payment method of the order, and if that card has
expired, the bank credits its replacement automatically.

Keep sections short

A section answers one question in one to a few short paragraphs. When a section grows long, break it with subheadings that each carry their own question, and check that every paragraph still stands on its own.

Be exact: names, numbers, conditions

Write product names, plan names, error codes and button labels exactly as customers see and type them. Search matches exact wording, and made-up shorthand for a product name or an error code will not be found when a customer pastes the real one.

The same goes for quantities. "Quickly" and "a few days" produce vague answers. Exact numbers produce exact answers.

Before:

Refunds are usually processed quickly after approval.

After:

Refunds are processed within 5 business days of approval. The bank
may take up to 7 more days to show the amount on the statement.

And state what a fact applies to. Customers do not mention their plan or version when they ask, so the section has to carry it.

Before:

Offline activation is available for some licenses.

After:

Offline activation is available on Plus and Team licenses running
version 4.2 or newer. Starter licenses require an internet
connection to activate.

State limitations together with the way around them

A vague limitation produces a dead-end answer. Name the limitation precisely and put the alternative in the same section, so Aiva can offer the way forward instead of only the "no".

Before:

Some payment methods may not support automatic renewal.

After:

Automatic renewal is not available for PayPal orders. PayPal orders
receive a renewal email 7 days before expiry with a checkout link
for the next term.

Steps that finish

Use a numbered list for any procedure, and end it with what the customer sees when it worked. Without the outcome, Aiva can walk someone through the steps but cannot confirm success or catch that something went wrong.

Before:

1. Open the account page.
2. Select the license under Licenses.
3. Click Deactivate.

After:

1. Open the account page.
2. Select the license under Licenses.
3. Click Deactivate.
4. The device disappears from the device list immediately, and the
   key can be activated on the new computer right away.

One subject per source

Keep each source on one subject. A single-subject source is easier to keep fresh and can be enabled or disabled on its own, and Aiva sees the source title as the label of its content, so a title that matches the content helps her attribute facts correctly.

The title field already labels the source. There is no need to repeat it as a heading inside the document.

From saved replies to documentation

Saved replies and past support answers are excellent raw material, and pasting them in unchanged is the most common mistake. A reply describes one customer's incident in conversation form. Knowledge states the general rule, in third person, with no greetings, apologies or direct address.

Before, a saved reply pasted as knowledge:

We have reset the activations on your key, so you should be able
to activate again now. Sorry for the trouble, and feel free to
reach out if this happens again!

After, the rule the reply was applying:

## Activation limit reached
 
When a license key reaches its device limit, the activation count
can be reset from the account page under Licenses. A reset is
available once every 30 days, and the key can be activated again
immediately afterwards.

Facts only

Knowledge content is treated as facts, never as instructions. Writing "always answer in a formal tone" or "never mention competitor products" into a source does not change Aiva's behavior, and it takes the place of content that could actually answer. Behavior settings live in the dashboard under AI settings.

Content that depends on your material

Some choices depend on your content, and there is no single right answer:

• Simple tables work. Introduce a table with a sentence saying what it covers, so the rows keep their meaning when read alone.
• Very long documents work when every section stands alone. Length itself is not a problem. Context-dependent sections are.
• Split a large source into several sources when it makes the content easier to maintain.
• Links can stay in the text. Aiva keeps their targets and can share them in an answer. Images are not read, so anything shown in a screenshot must also be written out as steps or text.