-
Notifications
You must be signed in to change notification settings - Fork 139
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs(ux-writing): Adds conversation design and chatbot guidelines. #4206
Conversation
Edit from check-in w Abi: let's release this alongside the chatbot, I'll make updates to align them better when the release is closer. We can also revisit these docs once published and remove anything that's extraneous/unnecessary, since some of this info is fairly high level |
Not a PR note but noticed the content isn't wrapping on mobile. @srambach any thoughts? |
Update - Adjusted this a bit to align with the chatbot extension, and I'm planning to move some top level info into an "about chatbot" kind of page via patternfly/chatbot#182 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks good to me overall! I can only see the one page (https://patternfly-org-pr-4206-site.surge.sh/patternfly-ai/conversation-design), so that's all I checked visually. I noted some suspected typos and added some questions/comments about some links.
packages/documentation-site/patternfly-docs/content/AI/conversation-design/chatbots.md
Outdated
Show resolved
Hide resolved
<GalleryItem> | ||
<Card isFullHeight isLarge > | ||
<CardTitle>AI-based chatbots</CardTitle> | ||
<CardBody>Bots that use technologies like natural language processing and generative AI to parse user input and decide how to response. Often makes for a more natural, free flowing conversation, but relies on a trustworthy AI model.</CardBody> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
<CardBody>Bots that use technologies like natural language processing and generative AI to parse user input and decide how to response. Often makes for a more natural, free flowing conversation, but relies on a trustworthy AI model.</CardBody> | |
<CardBody>Bots that use technologies like natural language processing and generative AI to parse user input and decide how to respond. Often makes for a more natural, free flowing conversation, but relies on a trustworthy AI model.</CardBody> |
|
||
## When should I use a chatbot? | ||
|
||
It is important to only use chatbots when they add value to the user experience. Do not use chatbots simply for the sake of novelty. Your users aren't likely to be excited to interact with a new chatbot feature, unless it directly helps them. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It is important to only use chatbots when they add value to the user experience. Do not use chatbots simply for the sake of novelty. Your users aren't likely to be excited to interact with a new chatbot feature, unless it directly helps them. | |
It is important to only use chatbots when they add value to the user experience. Do not use chatbots simply for the sake of novelty. Your users aren't likely to be excited to interact with a new chatbot feature, unless it directly helps them. |
|
||
## Best practices | ||
|
||
These best practices for conversation design will help ensure that your users needs are met and that their experience with your chatbot is positive and painless. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These best practices for conversation design will help ensure that your users needs are met and that their experience with your chatbot is positive and painless. | |
These best practices for conversation design will help ensure that your users' needs are met and that their experience with your chatbot is positive and painless. |
- Avoid open ended questions. If you ask any, make them very simple, increase pause time between messages, and tell users when they should type. | ||
- Be direct. Limit choices for users as much as possible and provide examples when you can. | ||
- Frame questions in terms of value for the user. | ||
- Unlike traditional content design, *don't lead with the benefit.* End with the benefit to be sure that its read and acted upon. Users should be able to complete an action solely based on a chatbot's last sentence. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- Unlike traditional content design, *don't lead with the benefit.* End with the benefit to be sure that its read and acted upon. Users should be able to complete an action solely based on a chatbot's last sentence. | |
- Unlike traditional content design, *don't lead with the benefit.* End with the benefit to be sure that it is read and acted upon. Users should be able to complete an action solely based on a chatbot's last sentence. |
...tation-site/patternfly-docs/content/PatternFly-AI/conversation-design/conversation-design.md
Outdated
Show resolved
Hide resolved
...tation-site/patternfly-docs/content/PatternFly-AI/conversation-design/conversation-design.md
Outdated
Show resolved
Hide resolved
...tation-site/patternfly-docs/content/PatternFly-AI/conversation-design/conversation-design.md
Show resolved
Hide resolved
<Card isFullHeight isLarge> | ||
<CardTitle>Rule-based chatbots</CardTitle> | ||
<CardBody>Bots that are based on a set of predefined rules. These use a planned, guided dialog, and have a script that the user must stay on. The script is written by a human, including any microcopy, rules, prompts, and responses.</CardBody> | ||
<CardFooter> <Button component="a" href="https://www.patternfly.org/ux-writing/chatbots" variant="link" icon={<ArrowRightIcon />} iconPosition="end"> View chatbot writing guidelines </Button></CardFooter> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will this link exist?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
oops, I actually meant to delete this page!
...ges/documentation-site/patternfly-docs/content/AI/conversation-design/conversation-design.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Rebecca Alpert <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Some pages are hidden
@@ -0,0 +1,75 @@ | |||
--- | |||
id: Conversation design | |||
section: PatternFly-AI |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Which sections do we want this and the chatbots.md files to appear in the nav? Should they be under patternfly-ai/conversation-design as different tabs?
if so, i think you should be able to do that by using
id: (page title)
section: PatternFly-AI
source: (page title again? ... really it's whatever you want to be on the tab)
ty for the reviews 😁 so, my bad for the confusion--I accidentally forgot to remove a couple files from this pr! I only want to add patternfly-ai/conversation-design via this PR. Any info that I removed from earlier pr iterations, which is more chatbot-specific, I'll add back to the chatbots subsection as part of this pr patternfly/chatbot#182. All of the various PRs would then combine to resemble this in the nav:
But please LMK if this plan doesn't make sense or if y'all think we should go about it differently @rebeccaalpert @nicolethoen |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm speechless!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks awesome! I checked the link to the chatbot and it should be ok with the structure change? Fingers crossed. :)
Closes #4001
Preview link: https://patternfly-org-pr-4206-site.surge.sh/patternfly-ai/conversation-design