-
Notifications
You must be signed in to change notification settings - Fork 77
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge remote-tracking branch 'origin/main' into release-3.0.0
- Loading branch information
Showing
39 changed files
with
1,441 additions
and
15 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| { | ||
| "label": "CLI Design", | ||
| "position": 5 | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| --- | ||
| sidebar_position: 1 | ||
| sidebar_title: Consistent | ||
| title: Consistent | ||
| --- | ||
|
|
||
| CLIs are the same across the whole product, follow our conventions and use our recommended frameworks. | ||
|
|
||
| ### Best practice | ||
| - Always use a command line library when available | ||
| - Always return a zero exit code to signal success | ||
| - Always return non-zero exit code to signal failure | ||
| - Always send your output to stdout | ||
| - Always send your messaging to stderr | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| ### Subcommands | ||
| - Use consistent subcommands | ||
| - Use consistent names for all subcommand levels | ||
| - Use clear and unique names for subcommands | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| ### Changes | ||
| - Always try to make additive changes | ||
| - Always warn users about non-additive changes | ||
| - Avoid making breaking changes | ||
| - Provide a migration period and strategy for breaking changes | ||
|
|
||
|  | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| --- | ||
| sidebar_position: 3 | ||
| sidebar_title: Efficient | ||
| title: Efficient | ||
| --- | ||
|
|
||
| import Separator from '@site/src/components/separator/Separator'; | ||
|
|
||
| Commands are scannable, giving users just the right amount of information at the right time. | ||
|
|
||
| ### Informing | ||
| - Keep users informed when processes are known to take time | ||
| - Give users time indicators when possible | ||
| - Use loading bars showing progress when possible | ||
| - Make things time out and notify users promptly | ||
| - Assume users need support | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| <Separator></Separator> | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| ### Robustness | ||
| - Ensure your program validates user input | ||
| - Ensure your program can recover and bring the system back to safety | ||
| - Ensure your program terminates when it’s invalid or fails | ||
| - Ensure system resilience by implementing retries and failovers | ||
| - Ensure your program cannot be misused or abused | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| <Separator></Separator> | ||
|
|
||
|  | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| --- | ||
| sidebar_position: 0 | ||
| sidebar_title: Getting started | ||
| title: Getting started | ||
| hide_table_of_contents: true | ||
| --- | ||
|
|
||
| import {Card, CardList} from '@site/src/components/Card'; | ||
|
|
||
| This guide provides support for CLI creators at Siemens to offer consistent and clear commands that can be easily understood by our customers. | ||
|
|
||
| <CardList> | ||
| <Card label="Consistent" isPrimary={true} size="big" link="cli/consistent" icon="stamp-filled" /> | ||
| <Card label="Logical" link="cli/logical" icon="bulb"/> | ||
| <Card label="Efficient" link="cli/efficient" icon="clock-filled" /> | ||
| <Card label="Helpful" link="cli/helpful" icon="inquiry" /> | ||
| <Card label="Human" link="cli/human" icon="user-filled" /> | ||
| </CardList> | ||
|
|
||
| Based on the open-source guide [CLIG](https://clig.dev/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| --- | ||
| sidebar_position: 4 | ||
| sidebar_title: Helpful | ||
| title: Helpful | ||
| --- | ||
|
|
||
| CLIs support users by giving suggestions, being empathetic and providing error messages to move them forward. | ||
|
|
||
| ### Support | ||
| - Always implement a help option with the two common flags: -h or --help | ||
| - Structure help sections with usage, commands, arguments, options and examples | ||
| - Provide help when users make invalid requests | ||
| - Provide documentation both at the terminal and online | ||
| - Document commands and extend documentation for your commands | ||
| - Provide auto-completion when possible | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ### Errors | ||
| - Keep users informed | ||
| - Provide text-based error descriptions | ||
| - Present errors logically, e.g. by location or type | ||
| - Present all errors where they are the most discoverable, e.g. at the end of the command line | ||
|
|
||
|  | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| --- | ||
| sidebar_position: 5 | ||
| sidebar_title: Human | ||
| title: Human | ||
| --- | ||
|
|
||
| import Separator from '@site/src/components/separator/Separator'; | ||
|
|
||
| Design your commands for humans. Have a conversation. Speak the Siemens brand: Authentic, open and engaging. | ||
|
|
||
| ### Interactivity | ||
| - Offer interactive modes when developing primarily for human interaction | ||
| - Tell users which environment they are in (interactive / non-interactive) | ||
| - Use --no-input when you don't want to interact with your terminal | ||
| - Ensure users can exit anytime | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| <Separator></Separator> | ||
|
|
||
|  | ||
|
|
||
| <Separator></Separator> | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| ### Output | ||
| - Return brief response messages, e.g. x done / x created / x named / x not done / x not created / x not named | ||
| - Respond by repeating command words, e.g. createdevice = device created / device not created | ||
| - Give command suggestions | ||
| - Use everyday, understandable language | ||
| - Use color when necessary and with reason | ||
| - Use well-known symbols to boost clarity when supported | ||
| - Tell users when there are state changes | ||
| - Avoid buzz words and jargon | ||
| - Avoid emojis to express emotions to align with our brand voice and style | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| <Separator></Separator> | ||
|
|
||
|  | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| --- | ||
| sidebar_position: 2 | ||
| sidebar_title: Logical | ||
| title: Logical | ||
| --- | ||
|
|
||
| import Separator from '@site/src/components/separator/Separator'; | ||
|
|
||
| Commands guide users through tasks logically and intuitively to remove doubt. | ||
|
|
||
| ### Arguments and flags | ||
| - Try to use flags instead of arguments | ||
| - Boolean flags must default to false and be set to true when present | ||
| - If the default of a boolean flag is true, use the prefix no- to flip the default | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| - Abbreviated flags are only used for frequent use cases | ||
| - Abbreviated flags must have full length versions | ||
| - Always use standard flag names when available | ||
| - Defaults must match the most common use case and follow the principle of least astonishment (POLA) | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| <Separator></Separator> | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| - Avoid creating order-dependent commands | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| - Ask for confirmation before executing long-lasting operations or unrecoverable actions | ||
| - Clearly state consequential actions | ||
| - Offer flags to bypass confirmation dialogs, e.g. -f / --force | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| - Never expose confidential information inside the CLI | ||
| - Use a prompt or read from a file to prevent exposing confidential information | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ### Naming | ||
| Use names that are: | ||
| - memorable | ||
| - logical | ||
| - short | ||
| - simple | ||
| - specific | ||
| - guessable | ||
| - lower case (small letters) | ||
| - without spacing | ||
| - without punctuation | ||
| - without special characters | ||
| - written in full (no abbreviations or aconyms unless unique) | ||
|
|
||
|  | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,4 @@ | ||
| { | ||
| "label": "iX Controls (Example)", | ||
| "position": 8 | ||
| "position": 9 | ||
| } |
4 changes: 4 additions & 0 deletions
4
packages/documentation/docs/conversational-design/designing-conversations/_category_.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| { | ||
| "label": "Designing conversations", | ||
| "position": 4 | ||
| } |
32 changes: 32 additions & 0 deletions
32
...ation/docs/conversational-design/designing-conversations/acknowledging-users.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| --- | ||
| sidebar_position: 2 | ||
| title: Acknowledging users | ||
| --- | ||
| # Acknowledging users | ||
| ## Overview | ||
|
|
||
| In conversations, humans like to be acknowledged to shows the other person is listening and understands the situation. When a chatbot acknowledges user input, it prompts users to continue interacting, boosts the overall user experience, and makes interactions more authentic. | ||
| ## Examples | ||
|
|
||
| **User:** Can you provide more details about our pricing plans? | ||
| **Chatbot:** Certainly! We have three pricing tiers: Basic, Premium, and Enterprise. | ||
|
|
||
| **User:** Is there a trial period for your software? | ||
| **Chatbot:** Of course! You can try our software free for 14 days. | ||
|
|
||
| **User:** Can I customize the dashboard layout? | ||
| **Chatbot:** Absolutely! You can rearrange widgets and choose your preferred layout. | ||
|
|
||
| In all these examples, the chatbot acknowledges the input and then continues with its response, building user confidence that the chatbot understood their query correctly. | ||
|
|
||
| **User:** Can you create a maintenance schedule in August for all ball valves within the refinery located in Hamburg? | ||
| **Chatbot:** Sure. Give me a moment. | ||
|
|
||
| Here, although there may be some lag time between the query and the response, the chatbot acknowledges the request and then signals they are working on the task. | ||
|
|
||
| ## Dos and Don’ts | ||
|
|
||
| - Do use discourse markers to acknowledge users (see grammar section) | ||
| - Do use interim acknowledgments if the query response takes time to load | ||
| - Do read out dialogs to test if any acknowledgments are naturally missing | ||
| - Don’t forget to balance efficiency with authenticity |
34 changes: 34 additions & 0 deletions
34
...tion/docs/conversational-design/designing-conversations/ad-hoc-conversations.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| --- | ||
| sidebar_position: 8 | ||
| title: Ad hoc conversations | ||
| --- | ||
| # Ad hoc conversations | ||
| ## Overview | ||
|
|
||
| Even in industrial scenarios, users test and play with chatbots. Some ad hoc interactions can be fun and build relationships between your users and chatbots, however some can be undesirable and damaging for your brand. To mitigate this risk, it’s important to implement filters and set up clear guidelines. Companies and projects can decide if they need to implement more than a basic response and give, for example, a warning message. Either way, most chatbots respond in the same way when it comes to offensive or inappropriate user queries. | ||
|
|
||
| ## Examples | ||
|
|
||
| **Chatbot:** I apologize, I’m not able to assist you with that request. How else can I help you? | ||
|
|
||
| Universally, chatbots start with an apology before anything else, even if it was the user that added inappropriate or offensive input. | ||
|
|
||
| **Chatbot:** I apologize if my previous response caused offense. I'm here to assist you with any other questions or tasks regarding your online portal. How can I assist you today? | ||
|
|
||
| Here the chatbot seeks to move the user back on course and reminds them of their use case. | ||
|
|
||
| **User:** What’s the weather today? | ||
| **Chatbot:** Certainly! Let’s check the weather today for you. | ||
|
|
||
| Other ad hoc conversations, such as talking about the weather or saying hello help build a bond between user and chatbot. Although we do not recommend training your chatbot to tell jokes with users in industrial settings, a certain number of ad hoc conversations are beneficial. | ||
|
|
||
| Finally, in the face of truly unprofessional and offensive input, the following example from Microsoft Copilot shows a clear set of standards and makes their ethical guidelines transparent: | ||
|
|
||
| **Copilot:** As an AI language model, I don't have personal opinions or feelings, but I am designed to follow ethical guidelines. I **do not** engage in discussions or create content that promotes racism, sexism, or any form of discrimination. If you encounter any inappropriate responses, please let me know, and I'll do my best to address them. | ||
| ## Dos and Don’ts | ||
|
|
||
| - Do consider training your chatbot to filter for a list of offensive terms | ||
| - Do consider localization and cultural nuances, such as “master” and “slave” | ||
| - Do train your chatbot to move users back on track | ||
| - Don’t forget to test and train for offensive user input | ||
| - Don’t forget to allow for some harmless non-work interactions |
33 changes: 33 additions & 0 deletions
33
...tation/docs/conversational-design/designing-conversations/confirming-request.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| --- | ||
| sidebar_position: 3 | ||
| title: Confirming requests | ||
| --- | ||
| # Confirming requests | ||
| ## Overview | ||
|
|
||
| Chatbots in industrial applications are sometimes required to carry out long-lasting and consequential changes to systems. Changing a system incorrectly can lead to substantial issues within a plant or a factory, such as not connecting a device properly, resetting a password without informing users, or onboarding new roles or user permissions incorrectly. To mitigate these risks, chatbots should always confirm user requests. | ||
| ## Examples | ||
|
|
||
| **Chatbot:** Do you want me to implement this? | ||
| **User:** Yes. | ||
| **Chatbot:** Shall I continue? | ||
| **User:** Yes. | ||
| **Chatbot:** Can I implement now with changes effective immediately? | ||
| **User:** Yes. | ||
| **Chatbot:** Are you sure? Changing user permissions may lead to accessibility issues. | ||
| **User:** Yes | ||
|
|
||
| This interaction is frustrating and inefficient. It seems as if the chatbot does not trust the request and therefore the user. This would break trust between human and machine and result in a negative user experience. We recommend asking for confirmation only once and, if necessary, giving warnings or alerting users to possible consequences at the same time. | ||
|
|
||
| **User:** Change elena_harrison@factory.com from general user to admin. | ||
| **Chatbot:** Sure. Changing from general user to admin means they can edit other user roles and permissions for all factories. Shall I continue? | ||
| **User:** Yes | ||
| **Chatbot:** Ok, elena_harrison@factory.com is now an admin. Can I assist you with anything else? | ||
|
|
||
| In this interaction we see a simple request for confirmation before completing the task. The chatbot clarifies the user knows the consequences and then fulfills the task. In these types of interactions, asking for confirmation has similar advantages to acknowledging users; it further removes doubt and builds user confidence that the chatbot has correctly comprehended the query and is able to respond accurately. | ||
| ## Dos and Don’ts | ||
|
|
||
| - Do make all confirmations clear and transparent before processing tasks | ||
| - Do mitigate risks associated with making changes to systems or processes | ||
| - Do add warnings and consequences for significant or hazardous changes | ||
| - Don’t ask for confirmation more than once |
Oops, something went wrong.