Contents

Known Issue: What To Do When X Happens

Known issues that occur again and again are worth sharing with your peers, particularly if you know of a workaround to resolve the persistent problem or you know that there is no workaround! Briefly outline what your known issue is about so that users immediately know how relevant the information is to them and whether it’s worth their while to read.

What Caused it?

Let users know more the underlying conditions that caused this issue to happen. It may be specific, for example, to a certain configuration or deployment or if users set things up in a certain way.

What Can You Do?

Here’s where you tell users the steps that they can take to avoid this issue from happening in the first place. If it’s inevitable that it will happen in certain situations, tell them a workaround to resolve things and get back on track. If the issue is unavoidable and unresolveable, state that there is “No Known Workaround” The main thing is to fully inform the reader!!

Who Can you Call?

[Optional] For certain known issues, you may want to tell users to call the Support team for more information. Alternatively, you might want to redirect the user to other product documentation that describes the subject matter in finer detail. Whatever you do, give the full contact details or provide the links so that users know what to do next!