Six months ago, the ScreenSteps team received several support tickets for setting up Single Sign-on (SSO).
These tickets required phone calls or lengthy back-and-forth emails before finally being resolved.
Now, we love helping our customers, but our team was frustrated that our self-help documentation was falling short for this particular operation. Admittedly, SSO can get a tad complicated—even I shuddered a little when I had to get involved with SSO troubleshooting—but isn't the point of self-help documentation that customers can perform tasks on their own without involving support?
Even though we had very detailed help articles for setting up SSO, apparently those articles weren’t very helpful to the majority of customers who were setting up Single Sign-on.
What was going on?
Three shortcomings with our existing help articles
Big picture ideas are easier to understand than the nitty gritty details. But if you want to set up SSO, you need nitty gritty details. So, naturally, things can get confusing. And it's critical that each step is performed perfectly. An extra "." can be the difference between users effortlessly logging in, and users unable to access ScreenSteps.
When I reviewed our help articles, I realized three main shortcomings:
- Too many articles about SSO (leaving users asking, "which one do I need?")
- Variables made articles difficult to follow (e.g. "if this, then that")
- Details were easy to skim over in long help articles (readers scrolled right past important information)
These shortcomings prevented our self-help docs for SSO from living up to their purpose—customers being able to actually help themselves. We needed to make some changes.
A new approach to writing help articles
All of this was going on at the same time our development team was creating a new article type called “Workflow Article.”
Workflow articles include three new features:
- Questions
- Answers
- Actions
Turns out, these three new features made it possible for me to address the three shortcomings in our SSO help articles.
Questions and Answers
The first shortcoming in our help docs was that we had too many articles related to SSO, making it difficult for readers to know which article they should begin with. I leveraged the new Questions and Answers features to help me consolidate about 20 help articles related to SSO setup to 1 help article.
The initial question is a launching point to help readers get on their way. Here's what it looks like:
At the top is some general information followed by a question: "What do you want to set up Single Sign-on with?"
Below the question are the available answers :
- Salesforce
- Google Apps
- Azure Active Directory
- PhenixID
- SAML (Security Assertion Markup Language)
- Remote Authentication
Each one of those answers sends readers down a different path of step-by-step instructions.
Considering moving your standard operating procedures from Word or PDF to an online knowledge base? Our guide will help.
Actions
Once readers have selected an option from a list of answers, they are shown an action. For example, here's what an action looks like for setting up a custom app in Google Apps:
Actions help readers focus on a few details at once without being overwhelmed. They also prevent readers from just scrolling through the help article, skipping important information.
Once the action is completed, the reader is prompted to "Click to continue" to either view the next action or question.
Decision trees
Questions and answers can be used at any point in the article. I used questions and answers at the beginning of the article to help readers choose a main path to SSO setup, but I can also use questions and answers in the middle of an article to help with those "if this, then that" situations.
For example, in the middle of the setup, readers need to decide whether they want to create an endpoint in a specific ScreenSteps site, or in the overall ScreenSteps account:
If you want an endpoint at the site level, then...
OR
If you want an endpoint at the account level, then...
Before the workflow article, these would have been links or a foldable sections that readers could easily skim over (and miss). But now, I can stop readers in the middle of the instructions and force them to make a critical decision. And once a reader chooses, the rest of the article is customized to match that context.
All 3 shortcomings are resolved with the workflow article
This new article type resolves all three shortcomings in the original help articles. I can combine several articles so that there is one source of truth for setting up SSO.
I can customize instructions based on the context of what the reader wants to do (if this, then that).
And I can chunk information so that it's not so overwhelming and details aren't skipped over.
Does it work?
Yes. It works beautifully. We recently tested the article out on several customers who asked for help setting up SSO. They were able to connect to SSO without any additional help from our support team.
We've also been using this article type with other help topics and we've seen similar results. End users are able to do complicated tasks on their own because the instructions are clearer and more specific.
Even more important than that, however, is that our support team has incredibly clear instructions to follow if a customer does call in asking for help. No more shuddering when an SSO ticket comes through. The article has very clear instructions and follows a logical path for updating the settings, giving our customer support team a consistent way to approach SSO questions.
Will this be available to ScreenSteps customers?
The ScreenSteps team is planning on making this article type available to customers in the Fall or Winter of 2019.
