Skip to content
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

Merged
merged 12 commits into from
Oct 10, 2024

Conversation

edonehoo
Copy link
Collaborator

@edonehoo edonehoo commented Aug 21, 2024

@edonehoo edonehoo self-assigned this Aug 21, 2024
@patternfly-build
Copy link
Contributor

patternfly-build commented Aug 21, 2024

@andrew-ronaldson andrew-ronaldson self-requested a review August 21, 2024 14:29
@edonehoo edonehoo marked this pull request as draft September 4, 2024 17:17
@edonehoo
Copy link
Collaborator Author

edonehoo commented Sep 5, 2024

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

@andrew-ronaldson
Copy link
Contributor

Not a PR note but noticed the content isn't wrapping on mobile. @srambach any thoughts?

image

@edonehoo edonehoo marked this pull request as ready for review October 2, 2024 18:29
@edonehoo
Copy link
Collaborator Author

edonehoo commented Oct 2, 2024

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

Copy link
Member

@rebeccaalpert rebeccaalpert left a 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.

<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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- 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.

<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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will this link exist?

Copy link
Collaborator Author

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!

Copy link
Collaborator

@nicolethoen nicolethoen left a 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
Copy link
Collaborator

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)

@edonehoo
Copy link
Collaborator Author

edonehoo commented Oct 7, 2024

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:

PatternFly AI

  • About AI
  • AI guidelines
  • Conversation design
  • Chatbot
    • About chatbot (where I'll move some of the info I just deleted from this pr)
    • Continue with chatbot specific docs etc

But please LMK if this plan doesn't make sense or if y'all think we should go about it differently @rebeccaalpert @nicolethoen

Copy link
Contributor

@andrew-ronaldson andrew-ronaldson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm speechless!

Copy link
Member

@rebeccaalpert rebeccaalpert left a 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. :)

@nicolethoen nicolethoen merged commit dcfbcae into patternfly:main Oct 10, 2024
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add UX writing guidelines for chatbots.
5 participants