docs(ux-writing): Adds conversation design and chatbot guidelines. #4206

edonehoo · 2024-08-21T13:39:14Z

Closes #4001
Preview link: https://patternfly-org-pr-4206-site.surge.sh/patternfly-ai/conversation-design

patternfly-build · 2024-08-21T13:49:26Z

Preview: https://patternfly-org-pr-4206-site.surge.sh

edonehoo · 2024-09-05T14:07:44Z

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 · 2024-09-14T13:14:20Z

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

edonehoo · 2024-10-02T18:30:47Z

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/virtual-assistant#182

rebeccaalpert

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

rebeccaalpert · 2024-10-04T23:18:09Z

packages/documentation-site/patternfly-docs/content/AI/conversation-design/chatbots.md

+<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>


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>

rebeccaalpert · 2024-10-04T23:18:38Z

packages/documentation-site/patternfly-docs/content/AI/conversation-design/chatbots.md

+
+## 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.


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.

rebeccaalpert · 2024-10-04T23:20:53Z

...ges/documentation-site/patternfly-docs/content/AI/conversation-design/conversation-design.md

+
+## 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. 


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.

rebeccaalpert · 2024-10-04T23:21:25Z

...ges/documentation-site/patternfly-docs/content/AI/conversation-design/conversation-design.md

+- 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. 


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.

...tation-site/patternfly-docs/content/PatternFly-AI/conversation-design/conversation-design.md

rebeccaalpert · 2024-10-04T23:34:09Z

packages/documentation-site/patternfly-docs/content/AI/conversation-design/chatbots.md

+<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>


Will this link exist?

oops, I actually meant to delete this page!

...ges/documentation-site/patternfly-docs/content/AI/conversation-design/conversation-design.md

Co-authored-by: Rebecca Alpert <[email protected]>

nicolethoen

Some pages are hidden

nicolethoen · 2024-10-07T15:29:30Z

...tation-site/patternfly-docs/content/PatternFly-AI/conversation-design/conversation-design.md

@@ -0,0 +1,75 @@
+---
+id: Conversation design
+section: PatternFly-AI


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 · 2024-10-07T16:04:16Z

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/virtual-assistant#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

andrew-ronaldson

I'm speechless!

rebeccaalpert

Looks awesome! I checked the link to the chatbot and it should be ok with the structure change? Fingers crossed. :)

edonehoo added 2 commits August 13, 2024 09:43

docs(chatbots): Adds chatbot design guidelines.

1e032d0

docs(ux-writing): Adds conversation design and chatbot guidelines.

0e8219b

edonehoo self-assigned this Aug 21, 2024

edonehoo added the Content label Aug 21, 2024

Merge branch 'v6' into iss4001

0f47a3b

andrew-ronaldson self-requested a review August 21, 2024 14:29

edonehoo and others added 2 commits August 28, 2024 17:19

File restructuring and small edits.

6ecaaf0

Merge branch 'v6' into iss4001

6485a29

edonehoo marked this pull request as draft September 4, 2024 17:17

edonehoo and others added 3 commits October 1, 2024 15:27

Merge branch 'main' into iss4001

3866c4f

Updates content to align with incoming chatbot extension.

554fb85

Merge branch 'main' into iss4001

9498897

edonehoo marked this pull request as ready for review October 2, 2024 18:29

edonehoo requested review from rebeccaalpert, nicolethoen and kaylachumley October 4, 2024 14:25

rebeccaalpert requested changes Oct 4, 2024

View reviewed changes

Apply suggestions from code review

b575bf2

Co-authored-by: Rebecca Alpert <[email protected]>

nicolethoen reviewed Oct 7, 2024

View reviewed changes

Removes unused files.

8ae6730

Fix link to chatbot page

8625cea

edonehoo requested review from rebeccaalpert and nicolethoen October 7, 2024 16:07

Fixing some typos

baf4c0c

andrew-ronaldson approved these changes Oct 9, 2024

View reviewed changes

rebeccaalpert approved these changes Oct 9, 2024

View reviewed changes

nicolethoen merged commit dcfbcae into patternfly:main Oct 10, 2024
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(ux-writing): Adds conversation design and chatbot guidelines. #4206

docs(ux-writing): Adds conversation design and chatbot guidelines. #4206

edonehoo commented Aug 21, 2024 •

edited

Loading

patternfly-build commented Aug 21, 2024 •

edited

Loading

edonehoo commented Sep 5, 2024 •

edited

Loading

andrew-ronaldson commented Sep 14, 2024

edonehoo commented Oct 2, 2024

rebeccaalpert left a comment •

edited

Loading

rebeccaalpert Oct 4, 2024

rebeccaalpert Oct 4, 2024

rebeccaalpert Oct 4, 2024

rebeccaalpert Oct 4, 2024

rebeccaalpert Oct 4, 2024

edonehoo Oct 7, 2024

nicolethoen left a comment

nicolethoen Oct 7, 2024

edonehoo commented Oct 7, 2024 •

edited

Loading

andrew-ronaldson left a comment

rebeccaalpert left a comment •

edited

Loading

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


		## 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.

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

docs(ux-writing): Adds conversation design and chatbot guidelines. #4206

docs(ux-writing): Adds conversation design and chatbot guidelines. #4206

Conversation

edonehoo commented Aug 21, 2024 • edited Loading

patternfly-build commented Aug 21, 2024 • edited Loading

edonehoo commented Sep 5, 2024 • edited Loading

andrew-ronaldson commented Sep 14, 2024

edonehoo commented Oct 2, 2024

rebeccaalpert left a comment • edited Loading

Choose a reason for hiding this comment

rebeccaalpert Oct 4, 2024

Choose a reason for hiding this comment

rebeccaalpert Oct 4, 2024

Choose a reason for hiding this comment

rebeccaalpert Oct 4, 2024

Choose a reason for hiding this comment

rebeccaalpert Oct 4, 2024

Choose a reason for hiding this comment

rebeccaalpert Oct 4, 2024

Choose a reason for hiding this comment

edonehoo Oct 7, 2024

Choose a reason for hiding this comment

nicolethoen left a comment

Choose a reason for hiding this comment

nicolethoen Oct 7, 2024

Choose a reason for hiding this comment

edonehoo commented Oct 7, 2024 • edited Loading

andrew-ronaldson left a comment

Choose a reason for hiding this comment

rebeccaalpert left a comment • edited Loading

Choose a reason for hiding this comment

edonehoo commented Aug 21, 2024 •

edited

Loading

patternfly-build commented Aug 21, 2024 •

edited

Loading

edonehoo commented Sep 5, 2024 •

edited

Loading

rebeccaalpert left a comment •

edited

Loading

edonehoo commented Oct 7, 2024 •

edited

Loading

rebeccaalpert left a comment •

edited

Loading