Skip to content

Commit

Permalink
docs(figma-plugin): use version id if provided by documentation (#1599)
Browse files Browse the repository at this point in the history
Co-authored-by: kathrin.schalber.ext <[email protected]>
  • Loading branch information
danielleroux and kathrinschalber authored Dec 12, 2024
1 parent 0fe4d52 commit 9205dc9
Show file tree
Hide file tree
Showing 8 changed files with 159 additions and 85 deletions.
12 changes: 6 additions & 6 deletions packages/documentation/docs/cli/consistent.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,25 +13,25 @@ CLIs are the same across the whole product, follow our conventions and use our r
- Always send your output to stdout
- Always send your messaging to stderr

![Best practice - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1025-1371&t=uLX24CWds4Z1hGKZ-1)
![Best practice - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20437&t=sN9pWBoxiiVCyam3-4)

![Best practice - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1025-1460&t=uLX24CWds4Z1hGKZ-1)
![Best practice - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20440&t=sN9pWBoxiiVCyam3-4)

### Subcommands
- Use consistent subcommands
- Use consistent names for all subcommand levels
- Use clear and unique names for subcommands

![Subcommands - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1025-1547&t=uLX24CWds4Z1hGKZ-1)
![Subcommands - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20446&t=sN9pWBoxiiVCyam3-4)

![Subcommands - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1025-1674&t=uLX24CWds4Z1hGKZ-1)
![Subcommands - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20502&t=sN9pWBoxiiVCyam3-4)

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

![Changes - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1021-6767&t=Oc1GlCBDeEX4Xbxj-1)
![Changes - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20475&t=sN9pWBoxiiVCyam3-4)

![Changes - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1021-6941&t=Oc1GlCBDeEX4Xbxj-1)
![Changes - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20488&t=sN9pWBoxiiVCyam3-4)
16 changes: 8 additions & 8 deletions packages/documentation/docs/cli/efficient.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,15 @@ Commands are scannable, giving users just the right amount of information at the
- Make things time out and notify users promptly
- Assume users need support

![Informing 1 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1035-9127&t=2JP2nlNciwS43htp-1)
![Informing 1 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20596&t=sN9pWBoxiiVCyam3-4)

![Informing 1 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1035-11427&t=2JP2nlNciwS43htp-1)
![Informing 1 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20584&t=sN9pWBoxiiVCyam3-4)

<Separator></Separator>

![Informing 2 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1035-9130&t=2JP2nlNciwS43htp-1)
![Informing 2 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20599&t=sN9pWBoxiiVCyam3-4)

![Informing 2 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1035-11430&t=2JP2nlNciwS43htp-1)
![Informing 2 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20587&t=sN9pWBoxiiVCyam3-4)

### Robustness
- Ensure your program validates user input
Expand All @@ -32,12 +32,12 @@ Commands are scannable, giving users just the right amount of information at the
- Ensure system resilience by implementing retries and failovers
- Ensure your program cannot be misused or abused

![Robustness 1 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1035-9133&t=2JP2nlNciwS43htp-1)
![Robustness 1 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20602&t=sN9pWBoxiiVCyam3-4)

![Robustness 1 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1035-11433&t=2JP2nlNciwS43htp-1)
![Robustness 1 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20590&t=sN9pWBoxiiVCyam3-4)

<Separator></Separator>

![Robustness 2 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1035-9136&t=2JP2nlNciwS43htp-1)
![Robustness 2 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20605&t=sN9pWBoxiiVCyam3-4)

![Robustness 2 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1035-11436&t=2JP2nlNciwS43htp-1)
![Robustness 2 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20593&t=sN9pWBoxiiVCyam3-4)
6 changes: 3 additions & 3 deletions packages/documentation/docs/cli/helpful.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ CLIs support users by giving suggestions, being empathetic and providing error m
- Document commands and extend documentation for your commands
- Provide auto-completion when possible

![Support - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1035-8879&t=2JP2nlNciwS43htp-1)
![Support - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20618&t=sN9pWBoxiiVCyam3-4)


### Errors
Expand All @@ -23,6 +23,6 @@ CLIs support users by giving suggestions, being empathetic and providing error m
- 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

![Errors - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1035-8921&t=2JP2nlNciwS43htp-1)
![Errors - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20612&t=sN9pWBoxiiVCyam3-4)

![Errors - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1035-9024&t=2JP2nlNciwS43htp-1)
![Errors - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20615&t=sN9pWBoxiiVCyam3-4)
18 changes: 9 additions & 9 deletions packages/documentation/docs/cli/human.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,19 +14,19 @@ Design your commands for humans. Have a conversation. Speak the Siemens brand: A
- Use --no-input when you don't want to interact with your terminal
- Ensure users can exit anytime

![Interactivity 1 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1037-12943&t=2JP2nlNciwS43htp-1)
![Interactivity 1 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20680&t=sN9pWBoxiiVCyam3-4)

![Interactivity 1 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1037-13477&t=2JP2nlNciwS43htp-1)
![Interactivity 1 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20737&t=sN9pWBoxiiVCyam3-4)

<Separator></Separator>

![Interactivity 2 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1037-12988&t=2JP2nlNciwS43htp-1)
![Interactivity 2 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20725&t=sN9pWBoxiiVCyam3-4)

<Separator></Separator>

![Interactivity 3 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1037-12991&t=2JP2nlNciwS43htp-1)
![Interactivity 3 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20728&t=sN9pWBoxiiVCyam3-4)

![Interactivity 3 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1037-13525&t=2JP2nlNciwS43htp-1)
![Interactivity 3 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20782&t=sN9pWBoxiiVCyam3-4)

### Output
- Return brief response messages, e.g. x done / x created / x named / x not done / x not created / x not named
Expand All @@ -39,12 +39,12 @@ Design your commands for humans. Have a conversation. Speak the Siemens brand: A
- Avoid buzz words and jargon
- Avoid emojis to express emotions to align with our brand voice and style

![Output 1 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1037-12994&t=2JP2nlNciwS43htp-1)
![Output 1 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20731&t=sN9pWBoxiiVCyam3-4)

![Output 1 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1037-13528&t=2JP2nlNciwS43htp-1)
![Output 1 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20785&t=sN9pWBoxiiVCyam3-4)

<Separator></Separator>

![Output 2 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1037-12997&t=2JP2nlNciwS43htp-1)
![Output 2 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20734&t=sN9pWBoxiiVCyam3-4)

![Output 2 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1037-13531&t=2JP2nlNciwS43htp-1)
![Output 2 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20788&t=sN9pWBoxiiVCyam3-4)
28 changes: 14 additions & 14 deletions packages/documentation/docs/cli/logical.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,45 +13,45 @@ Commands guide users through tasks logically and intuitively to remove doubt.
- 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

![Arguments and flags 1 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-2260&t=2JP2nlNciwS43htp-1)
![Arguments and flags 1 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20509&t=sN9pWBoxiiVCyam3-4)

![Arguments and flags 1 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-6716&t=2JP2nlNciwS43htp-1)
![Arguments and flags 1 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20550&t=sN9pWBoxiiVCyam3-4)

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

![Arguments and flags 2 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-2348&t=2JP2nlNciwS43htp-1)
![Arguments and flags 2 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20532&t=sN9pWBoxiiVCyam3-4)

![Arguments and flags 2 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-6720&t=2JP2nlNciwS43htp-1)
![Arguments and flags 2 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20553&t=sN9pWBoxiiVCyam3-4)

<Separator></Separator>

![Arguments and flags 3 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-2351&t=2JP2nlNciwS43htp-1)
![Arguments and flags 3 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20535&t=sN9pWBoxiiVCyam3-4)

![Arguments and flags 3 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-6723&t=2JP2nlNciwS43htp-1)
![Arguments and flags 3 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20556&t=sN9pWBoxiiVCyam3-4)

- Avoid creating order-dependent commands

![Arguments and flags 4 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-2354&t=2JP2nlNciwS43htp-1)
![Arguments and flags 4 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20538&t=sN9pWBoxiiVCyam3-4)

![Arguments and flags 4 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-6726&t=2JP2nlNciwS43htp-1)
![Arguments and flags 4 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20559&t=sN9pWBoxiiVCyam3-4)

- 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

![Arguments and flags 5 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-2357&t=2JP2nlNciwS43htp-1)
![Arguments and flags 5 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20541&t=sN9pWBoxiiVCyam3-4)

![Arguments and flags 5 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-6729&t=2JP2nlNciwS43htp-1)
![Arguments and flags 5 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20562&t=sN9pWBoxiiVCyam3-4)

- Never expose confidential information inside the CLI
- Use a prompt or read from a file to prevent exposing confidential information

![Arguments and flags 6 - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-2360&t=2JP2nlNciwS43htp-1)
![Arguments and flags 6 - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20544&t=sN9pWBoxiiVCyam3-4)

![Arguments and flags 6 - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-6732&t=2JP2nlNciwS43htp-1)
![Arguments and flags 6 - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20565&t=sN9pWBoxiiVCyam3-4)


### Naming
Expand All @@ -68,6 +68,6 @@ Use names that are:
- without special characters
- written in full (no abbreviations or aconyms unless unique)

![Naming - Do](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-2363&t=2JP2nlNciwS43htp-1)
![Naming - Do](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20547&t=sN9pWBoxiiVCyam3-4)

![Naming - Don't](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?node-id=1034-6735&t=2JP2nlNciwS43htp-1)
![Naming - Don't](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4406-20568&t=sN9pWBoxiiVCyam3-4)
2 changes: 1 addition & 1 deletion packages/documentation/docs/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ title: Roadmap

# Siemens Industrial Experience Roadmap

![Roadmap](https://www.figma.com/design/YSvLeddwfyjLx8G5QWOTCH/Documentation-Visuals?type=design&node-id=694-130&mode=design&t=7oYieUSvKMurFcpx-11)
![Roadmap](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=4407-5564&t=sN9pWBoxiiVCyam3-4)

<p className="text-l-title">
We’re constantly improving our design system for you by extending the component library, developing our user guidance and ensuring the system is reliable and easy to use.
Expand Down
Loading

0 comments on commit 9205dc9

Please sign in to comment.