[The question or problem, in the reader's words]

One problem per article. Replace the blue placeholders, delete the grey notes, and delete any section this article doesn't need.

Article ID

[KB-NNNN]

Type

[Troubleshooting / how-to / question / known issue / policy]

Applies to

[Product and version, plan, platform, role]

Audience

[Customers / support agents / employees]

Owner

[Team or person]

Last reviewed

[YYYY-MM-DD]

Search terms

[Words readers use, the exact error text, internal names]

See a weak title next to a strong one

Weak: Bank connection lifecycle

Strong: Bank feed stopped updating (“Reconnect your bank” banner)

The strong one uses the reader's words and the exact banner text, so it matches either search.

Answer

One or two sentences that solve the problem or answer the question. Many readers stop here.

[The fix or the short answer]

Applies to

  • Product and version: [name and version, or all versions]

  • Plan or edition: [which plans]

  • Platform: [web, Windows, macOS, iPhone, Android]

  • Role: [who can do this, such as Owner or Admin]

Before you start

  • [Permission or role needed]

  • [Accounts, files or information to have ready]

  • [Time it takes]

Steps

  1. [Where to go, then the action]. You should see: [result]

  2. [Action]. You should see: [result]

  3. [Action]. You should see: [result]

One action per step, named as on the screen. Copy button and menu labels from the product, put › between menu levels, and end each step with what the reader should see.

See filled-in steps

  1. Go to Settings › Bank connections. You should see your bank with a red Disconnected label.

  2. Select Reconnect. Your bank's sign-in page opens in a new window.

  3. Sign in and approve access for Countwell. The window closes and the label turns green.

From an invented bookkeeping app. Every step ends with something the reader can check.

Cause

Optional. Why it happens, in plain words. Leave it out of how-to and question articles.

[Why this happens]

If this didn't help

  • Try next: [the next most likely fix, or a link to it]

  • Contact: [where to ask for help]

  • Include: [what to send, such as the error text and the time it happened]

  • Never send: [passwords, full card numbers or other secrets]

Related articles

  • [The likely next question]

  • [A related task]

Other article types

Not a troubleshooting article? Keep the title, the answer and the details table, and swap the sections below the answer for these.

Known issue

  • Status: investigating, fix scheduled or fixed, with the version

  • First seen: the date

  • Affects: who and what

  • Workaround: what to do until the fix ships

  • Updates: one dated line per change

Question

  • Short answer: yes or no first, then the condition

  • Details: the steps or limits, if any

  • Related: the full how-to article

Policy

  • The rule: in one or two sentences

  • Exceptions: who or what is treated differently

  • Effective date: when the rule took effect

  • Full policy: a link to the complete text

Before you publish

  • The title uses the reader's words, with any error text quoted exactly

  • The answer solves the problem in two sentences or fewer

  • Applies to lists every version, plan or platform that changes the answer

  • Every step names the screen and ends with what the reader should see

  • The owner and the last-reviewed date are filled in

  • Unused sections are deleted, not left empty