Template · Updated
Known issues page template
Every product has bugs waiting for a fix. Telling customers about them openly costs less than answering the same report fifty times, and it builds more trust than silence. This template keeps the page short, current, and useful.
Short answer
A known issues page lists problems you know about but haven't fixed yet: what's affected, who it affects, a workaround if there is one, and when the entry was last updated. It saves customers from reporting the same bug and gives support one link to send. Remove entries as soon as they're fixed and note the fix in your release notes.
When to use this template
Use this template for bugs and limitations that affect a noticeable number of customers and won't be fixed immediately. It isn't a status page for outages; link your status page for those. Keep one page for the whole product, or one per area if you have many entries. Link the page from your status page, your troubleshooting articles, and the saved replies your team uses, so customers find it before they write in.
What goes in it
A short entry per issue
Title it with what customers notice, not the internal bug name.
Who's affected
Which plans, platforms, browsers, or settings, so unaffected customers can stop worrying.
Workaround
The steps to get the job done anyway, or a plain “no workaround yet”.
Status and last updated
Investigating, fix in progress, or fix scheduled, with the date of the last update.
Fixed issues move out
When it's fixed, remove the entry and mention the fix in the release notes.
The template
Copy it into your help center editor and replace the bracketed parts.
# Known issues
Problems we know about and are working on. For outages, see [status page](link).
Last reviewed: [date]
## [What customers notice]
Affects: [plans, platforms, browsers, or settings].
Workaround: [steps, or “No workaround yet.”]
Status: [Investigating / Fix in progress / Fix scheduled for date].
Last updated: [date].
## [Next issue]
Affects: [...].
Workaround: [...].
Status: [...].
Last updated: [date].Example: a Ledgerloop known issue
# Known issues
Problems we know about and are working on. For outages, see status.example.com.
Last reviewed: October 6
## PDF invoices show the wrong currency symbol for Swiss francs
Affects: invoices in CHF downloaded as PDF. Emails and the online invoice are correct.
Workaround: send the online invoice link instead of the PDF.
Status: Fix in progress.
Last updated: October 6.Mistakes to avoid
- Using internal bug names customers won't recognize or search for.
- Leaving fixed issues on the page, so it stops being trustworthy.
- No “who's affected”, so every customer worries.
- No dates, so readers can't tell if an entry is current.
- Using it for outages instead of a status page.
How to keep this article current
A known issues page is only useful while it's current, which means removing entries the moment they're fixed. usedocs reads merged pull requests and releases; so when a fix changes behavior the page describes, the known issues page can get a proposed edit like any other article. Remove the entry when you approve it, and mention the fix in the release note. When customers ask the assistant about a problem that isn't listed, the question shows up as a gap so you can decide whether it belongs on the page.
FAQ
What's the difference between known issues and a status page?
A status page covers outages and incidents; a known issues page covers bugs and limitations that persist while a fix is built.
Does a public known issues page hurt trust?
Usually the opposite. Customers trust a product that's honest about bugs more than one that's silent.
How often should it be reviewed?
Every release, to remove fixed issues, and weekly while issues are active.
Should every bug be listed?
No, only issues that affect a noticeable number of customers and won't be fixed right away.
What happens when an issue is fixed?
Remove the entry and mention the fix in your release notes.
Should support link the known issues page in replies?
Yes. One link that stays current beats retyping the workaround, and customers can check back for updates.
How detailed should a workaround be?
As detailed as a normal how to article: numbered steps a customer can follow without help.
Should the page give fix dates?
Only when you're confident. “Fix in progress” with a recent update date is better than a date you miss, because a missed date costs more trust than no date at all.