Knowledge base articles

The knowledge base is your team's own library of how-tos, checklists and processes. Articles in it are for the whole team and are not tied to one customer. (Articles about a single customer live with that customer: see Customer documentation and records.)

Folders#

Folders organise the knowledge base, and they can go inside each other, for example Exchange Online inside Microsoft 365.

To add a folder:

1. Open Docs and choose Knowledge base.
2. Press New folder.
3. Enter a Name.
4. Under Inside, choose The top level or the folder it belongs in.
5. Press Add folder (or Cmd+Enter).

Click a folder in the sidebar to see only its articles. The number beside each folder is how many articles it holds. A folder can be limited to named people, roles and teams, and can ask for approval of the articles in it. See Folders, sharing and history.

Writing an article#

1. Press New article on the knowledge base (or choose a folder first, and the new article goes into it).
2. Tenvara asks What are you writing? Choose Blank article, one of the starters (Standard operating procedure, Runbook or Customer overview), or one of Your templates. A starter or template fills in the title and body; nothing is saved until you save.
3. Type the Title at the top.
4. Write the body in the editor. The toolbar has headings, bold, italic, underline, strikethrough, inline code, links, bulleted and numbered lists, quotes, code blocks, a divider, tables, images and attachments. You can paste screenshots straight in. Type / for the blocks below.
5. Fill in the panel on the right (below).
6. Press Save article, or Cmd+S.

Templates#

Any knowledge base article can become a template from its ... menu: Save as template..., with a line saying what it is for. A template is badged Template, has its own view in the article list, and is never on the portal, never due for review, and left out of ticket suggestions and the AI's answers. Stop it being a template puts it back. Images in a template are copied for each new article, so the two never share a file.

Blocks: callouts, task lists, links and credentials#

Type / in the editor for:

• Callouts: Note, Warning and Danger boxes around ordinary text.
• Task lists: steps with tick boxes. Readers tick them off for themselves as they work; the article never changes. Save progress keeps a run (who, which steps, when) that anyone can carry on from Saved runs.
• Links to an article, record, device, contact, site, ticket or customer. The link always shows the current name, with its hover card, and the device or contact page lists the articles that mention it.
• Insert credential (customer articles): one of the same customer's credentials, shown with its username, copy and Reveal. Readers reveal it with their own vault access, and every reveal is logged as usual; readers without access see "Credential: name (no access)". The secret never goes into the article.

On the portal, the public knowledge base and share links, links become plain names and embedded credentials are left out.

AI in the editor#

When AI is switched on, the editor's AI button works on the selection, or the whole article when nothing is selected: Tidy up and fix spelling, Make it a numbered procedure, Shorten, Write a summary for the portal and Check for secrets. Each answer is shown as a difference against what is there; nothing changes until you press Accept, and nothing is saved until you save.

Check for secrets finds passwords, PINs, Wi-Fi keys, API keys, private keys, recovery codes and licence keys pasted into the text. A pattern check runs on your own install first, so obvious secrets are flagged even when AI is off. On a customer's article, Move into the vault turns each into a credential and embeds it in its place; Take it out replaces it with "[removed]". See Setting up AI for switching AI on.

The side panel#

Images and attachments are limited to 25 MB each, the same as ticket attachments.

Tip: Leaving the editor with unsaved changes asks you first, so you will not lose work by clicking away.

When two people edit at once#

If someone else saves the article while you are editing, your save does not overwrite theirs silently. The editor tells you, and you can either reload to see their version or keep your text and save it over theirs. Their version stays in the history either way.

Reading an article#

Click an article to open it. The header shows its folder, owner, when it was last updated and by whom, and its version number.

The panels on the right show:

• Linked to: the tickets, devices, contacts and sites the article is linked to. Press Link to add one. Linked articles show on those pages, and on a ticket they are suggested first.
• Related: other articles, records and credentials related to this one, both ways, with an optional label such as "runs on". Press Relate to add one. Articles that link here in their text are listed too.
• Share links: read-only links for people without a sign-in. See Folders, sharing and history.
• Looking after it: the owner, the review schedule, whether it is in the customer portal (Staff only or published) and its tags.
• History: the latest versions, with All versions to open the full history.

Keyboard shortcuts#

More actions#

The ... menu on an article has:

• Publish to the customer portal (or take it off the portal).
• Duplicate..., to copy it to another folder or a customer.
• Save as template....
• Version history.
• Copy link, to paste the article's address into a chat or ticket.
• Share a read-only link....
• Print and Download PDF, in your branding with the article's details. Callouts keep their colours, task lists print as empty boxes and embedded credentials as their name with the secrets hidden.
• Archive and Delete article. Deleted articles go to the recycle bin.

Approval before an article goes live#

Articles can need approval before readers see them. Approval is asked for by a folder (and the folders inside it), or for the whole knowledge base or every customer's documentation in Settings > Documentation, under Approval. Nothing needs approval to start with.

Where approval is needed, an article is Draft, In review or Published:

1. Write and save as often as you like. A change to a published article is kept apart as a draft: readers, ticket suggestions, the AI, the chat bot and the portal keep reading the published text.
2. Press Submit for review, with an optional note. While it waits it cannot be changed, only taken out of review.
3. The folder's approvers (else the people in Who approves documentation, else the administrators) are told in the app and by email. It is an ordinary request in Approvals, so reminders, delegation and expiry apply.
4. An approver opens the article, uses See what changes to compare it with the live text, and presses Approve and publish, or Send back with a comment. A sent-back change returns to the writer as a draft with the comment shown.

With Four eyes on (it is to start with), nobody approves their own change. Docs > Awaiting my review lists what is waiting for you, with a count. Every step is on the article's activity.

Version history#

Every save that changes the title or the text keeps a version. Changes to tags, owner or dates do not make new versions.

1. Open the article and press H, or choose All versions.
2. Pick a version on the left. J and K move between versions.
3. Choose Version N to read it as it was, or Changes since to compare it with the current version line by line. Unchanged stretches are folded away.
4. To go back to an older version, restore it. Restoring saves it as a new version, so nothing is lost.

Marking an article reviewed#

When you have checked an article is still right, press Mark reviewed (or R). If the article repeats its review, the next review date moves on by the interval you set. See Reviews and the vault audit log for the list of articles due.

Moving articles#

To move an article to another folder, edit it and change Folder, or select several in the list and use Move to folder. You can also turn a knowledge base article into a customer article, or the other way round, by changing Where it lives.

Note: Moving an article to another customer, or into the knowledge base, takes it off the customer portal unless the same change publishes it again. This stops one customer's article appearing to another.