From 1a9aa45ca682e923efd02a92d684141ba3c282ca Mon Sep 17 00:00:00 2001
From: Betti <167863867+bettiifr@users.noreply.github.com>
Date: Thu, 19 Dec 2024 09:16:09 +0100
Subject: [PATCH] docs(charts): align writing (#1496)
Co-authored-by: tokyojen <143795032+tokyojen@users.noreply.github.com>
Co-authored-by: matthiashader <144090716+matthiashader@users.noreply.github.com>
---
.../documentation/docs/controls/charts/3d.md | 31 ++++----
.../docs/controls/charts/bar-chart.md | 21 ++++--
.../docs/controls/charts/gauge-chart.md | 26 +++++--
.../docs/controls/charts/line-chart.md | 25 +++++--
.../docs/controls/charts/overview.md | 70 ++++++++++++++++---
.../docs/controls/charts/pie-chart.md | 15 ++--
.../docs/controls/charts/special-chart.md | 16 ++---
7 files changed, 152 insertions(+), 52 deletions(-)
diff --git a/packages/documentation/docs/controls/charts/3d.md b/packages/documentation/docs/controls/charts/3d.md
index e7da159881..bbd8b2a500 100644
--- a/packages/documentation/docs/controls/charts/3d.md
+++ b/packages/documentation/docs/controls/charts/3d.md
@@ -1,33 +1,40 @@
import Playground from '@site/src/components/PlaygroundV3';
-# 3D-Charting
+# 3D charts
-The `echarts-gl` package extends ECharts to support 3D visualizations, enabling you to create immersive and interactive charts.
-With this package, you can design a variety of 3D charts, including:
+3D charts are a powerful way to visualize data in three dimensions. They provide a more immersive and interactive experience compared to traditional 2D charts. We typically use 3D charts to represent complex data sets or to visualize data in a more engaging way.
+
+The `echarts-gl` package extends ECharts to support 3D visualizations. With this package, you can design a variety of 3D charts, including:
- 3D scatter plots
- 3D bar charts
- 3D surface plots
+
+
+
## Installation
+To install the `echarts-gl` package, run the following command:
+
```sh
npm install --save @siemens/ix-echarts
```
## Import
+To use 3D charts, import the `echarts-gl` package into your project:
+
```typescript
import 'echarts-gl';
```
-## Example
-
-### Basic
+## Dos and Don'ts
-
-
+- Do use with data that's best seen and interpreted in multiple dimensions
+- Don’t use 3D charts for simple data that can be effectively represented with 2D charts
+- Don’t overuse 3D charts as they can make the data harder to interpret
\ No newline at end of file
diff --git a/packages/documentation/docs/controls/charts/bar-chart.md b/packages/documentation/docs/controls/charts/bar-chart.md
index d24662d06a..f72e216d11 100644
--- a/packages/documentation/docs/controls/charts/bar-chart.md
+++ b/packages/documentation/docs/controls/charts/bar-chart.md
@@ -1,10 +1,12 @@
import Playground from '@site/src/components/PlaygroundV3';
-# Bar chart
+# Bar charts
-## Examples
+Bar charts display data using rectangular bars. The length of each bar is proportional to the value it represents. Bar charts are commonly used to compare the values of different categories. We typically use bar charts to visualize data that is categorical or ordinal in nature.
-### Bar chart horizontal
+### Bar chart
+
+Common bar charts normally compare the values of different categories where the length of the bars are proportional to their values.
-### Bar chart horizontal stacked
+### Stacked bar chart
+
+Stacked bar charts are typically used to visualize the relationship between the parts and the whole. Each bar is divided into segments, with each segment representing a different category.
+## Dos and Don'ts
+
+- Do start the Y-axis at zero and label axes clearly
+- Do use short and clear category names
+- Do include context and additional information when necessary
+- Do arrange categories and bars in a logical order
+- Don’t use too many bars in one chart
+- Don’t overcrowd charts with colors and categories, especially the stacked variant
+- Don’t use stacked bars if the total value is not important
diff --git a/packages/documentation/docs/controls/charts/gauge-chart.md b/packages/documentation/docs/controls/charts/gauge-chart.md
index ae5832fd9f..90ef4fc38e 100644
--- a/packages/documentation/docs/controls/charts/gauge-chart.md
+++ b/packages/documentation/docs/controls/charts/gauge-chart.md
@@ -1,10 +1,13 @@
import Playground from '@site/src/components/PlaygroundV3';
-# Gauge chart
+# Gauge charts
-## Examples
+Gauge charts are a type of chart that displays data using a dial or needle to indicate a value within a specific range. Gauge charts are commonly used to visualize performance metrics, such as speedometers, progress meters, and other KPIs. We typically use gauge charts to represent a single value within a range of values.
+
+### Metric gauge charts
+
+Metrics gauge charts, also known as dial or speedometer charts, are an effective way to visualize key performance indicators (KPIs) and other metrics. These charts indicate the current value of a metric within a predefined range, often segmented into different zones, e.g. red for poor performance, green for good performance, etc.
-### Performance metrics gauge
-### Progress circle gauge
+### Circle gauge charts
+
+Circle gauge charts, also known as radial progress charts or circular progress bars, are a visually appealing way to represent data and track progress towards a goal. These charts use a circle to display the percentage of completion, making it easy to quickly grasp the status of a project or task. The circle is typically filled in proportion to the progress made, with the center often displaying the percentage value.
-### Progress arc gauge
+### Arc gauge charts
+
+Arc gauge charts, also known as semi-circular progress bars, are a dynamic way to visualize data and track progress. Unlike circle charts, arc gauge charts use a semi-circle or arc to represent the percentage of completion. This design can be particularly effective in dashboards and user interfaces where users need a clear and engaging visual representation but space is limited.
+
+## Dos and Don'ts
+
+- Do keep it simple and easy to read, with a clear needle and well-defined ranges
+- Do use color coding, e.g. green for good, red for danger, etc. to indicate different ranges
+- Do label ranges and the needle value clearly to avoid confusion
+- Don’t overcrowd the gauge with too many ranges or labels
+- Don’t use gauge charts for visualizing complex data or large datasets
+- Don’t use similar colors for adjacent ranges to avoid confusion
diff --git a/packages/documentation/docs/controls/charts/line-chart.md b/packages/documentation/docs/controls/charts/line-chart.md
index 6190b70879..9b5c214dc9 100644
--- a/packages/documentation/docs/controls/charts/line-chart.md
+++ b/packages/documentation/docs/controls/charts/line-chart.md
@@ -1,11 +1,12 @@
import Playground from '@site/src/components/PlaygroundV3';
-# Line chart
+# Line charts
+Line charts display data as a series of data points connected by straight line segments. Line charts are commonly used to visualize trends over time or compare two variables. We typically use line charts to visualize continuous data.
-## Examples
+### Basic line charts
-### Basic line chart
+Basic line charts use a series of data points connected by straight lines to show changes in values, making it easy to identify patterns, trends and fluctuations. Line charts are particularly effective for displaying continuous data, such as stock prices, temperature changes or sales figures. Their simplicity and clarity make them a popular choice for dashboards, where understanding data trends is essential.
-### Multi-y-axis line chart
+### Multi-y-axis line charts
+
+Multi-y-axis line charts are used to compare multiple data series that have different scales or units of measurement. By using multiple y-axes, you can display data with different ranges on the same chart, making it easier to compare trends and relationships between variables. Multi-y-axis line charts are particularly useful when visualizing data with distinct patterns or trends.
-### Advanced line chart
+### Advanced line charts
+
+Advanced line charts are an enhanced version of basic line charts, designed to provide deeper insights and a more detailed analysis of data trends. These charts often incorporate features such as multiple data series, interactive elements, and additional annotations to highlight key points or events. Advanced line charts can also include trend lines, moving averages and other statistical tools to help identify patterns and correlations.
+
+## Dos and Don'ts
+
+- Do start the Y-axis at zero and label axes clearly
+- Do use contrasting colors for multiple lines to better distinguish different data series
+- Do use consistent intervals on axes
+- Do highlight important data points
+- Do use visual cues to show gaps in data
+- Don’t overcrowd the chart with colors
+- Don’t clutter the chart with too many lines, we recommend no more than 7 lines
\ No newline at end of file
diff --git a/packages/documentation/docs/controls/charts/overview.md b/packages/documentation/docs/controls/charts/overview.md
index 63b34796c3..d966d1fd6e 100644
--- a/packages/documentation/docs/controls/charts/overview.md
+++ b/packages/documentation/docs/controls/charts/overview.md
@@ -6,21 +6,36 @@ import Playground from '@site/src/components/PlaygroundV3';
# Basics
Siemens Industrial Experience provides a theme for the popular chart library [ECharts](https://echarts.apache.org/handbook/en/get-started).
-This lets you harness the power of ECharts with seamless integration into the Siemens Industrial Experience styleguide.
+This lets you seamlessly integrate ECharts into the Siemens Industrial Experience design system.
+ECharts is a third-party library distributed under [Apache License 2.0](https://www.apache.org/licenses).
+
-ECharts is a third party library distributed under [Apache License 2.0](https://www.apache.org/licenses).
+
-
+## Attributes
+| Name | Description |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Axes** | Axes are used to display the data in a chart. They are the horizontal and vertical lines that form the chart's grid. Axes are labeled to indicate what data they represent. |
+| **Scale** | Scales are used to map data values to a visual representation. The scale type is determined by the type of data being visualized. |
+| **Labels** | Labels are used to describe the dimensions represented, often including units of measurement, e.g. “Distance traveled (m)”. |
+| **Grid lines** | Grid lines help to visually align data points within the chart. |
+| **Legend** | Legends explain the symbols, colors or patterns used in the chart to represent different data sets. You can toggle the visibility of the data series by clicking on the date in the legend. |
+| **Tooltip** | Tooltips provide more details about data while hovering over the area. |
+| | |
## Installation
+To install the Siemens Industrial Experience ECharts theme, follow the steps below:
+
```sh
npm install --save @siemens/ix-echarts
```
-First, import the `registerTheme` function from our module. Then, invoke this function, passing in your `echarts` instance as an argument. You don't need to provide the `echarts` instance if it is provided globally in your `window` object when using vanilla Javascript. Once this is done, you’ll be able to utilize the `brand-dark`, `brand-light`, `classic-dark`, and `classic-light` themes for your chart.
+1. Import the `registerTheme` function from our module.
+2. Invoke this function, passing in your `echarts` instance as an argument. You do not need to provide the `echarts` instance if it's provided globally in your `window` object when using vanilla Javascript.
+3. Once this is done, you’ll be able to utilize the `brand-dark`, `brand-light`, `classic-dark` and `classic-light` themes for your chart.
```typescript
import { registerTheme } from '@siemens/ix-echarts';
@@ -28,11 +43,29 @@ import { registerTheme } from '@siemens/ix-echarts';
registerTheme(echarts);
```
-### Angular
+
+For Angular, make sure to correctly add `NgxEcharts` in your module file.
+
+
+### Colors
+
+The Siemens Industrial Experience ECharts theme provides a set of colors that are used to style the charts. These colors are optimized for accessibility and readability.
+
+**Categorical data**
+For easily distinguishable data series where each category is distinct but not ordered, we recommend the following color sequence.
+Example: Different product types or regions.
+
+
+
+**Sequential data**
+For ordered data, we recommend using every second color, e.g. chart-1, chart-3, chart-5, etc. Example: monthly data.
+
+
-Please make sure to correctly add `NgxEcharts` in your module file.
+**Comparative data**
+For comparing data within a category, we recommend using the matching -40 color with 40% opacity. Example: last year and current year.
-## Examples
+
-## Empty state
+### Loading indicators
+
+A loading indicator provides users with visual feedback that the chart is being processed and will be displayed shortly. The loading indicator should be displayed when the chart is loading data or rendering, to visually indicate that the chart is not ready yet.
+
+### Empty states
+
+An empty state occurs when a user first opens an application, no data is available, or the user has filtered out all data. The empty state should be visually distinct from the loading state and should provide a clear message to the user. This message should explain why the empty state is being displayed and provide guidance on how to proceed.
+
+### Failure and error messages
+
+A failure occurs when no data can be displayed within the chart. This can happen for various reasons, such as connection failure and missing data. Error messages have the following elements to help users understand and resolve any issues:
+
+- State problem: What happened? Add a clear reason for the error, e.g. “No data available”
+- Explain cause: Why did the error appear? A clear and concise message explaining why the error happened, e.g. "Connection failure"
+- Give solution: What can the user do to proceed?
+ Add clear instructions for the user regarding what to do next to resolve the error, e.g. “Try again”
+
+For more detailed information and examples, see the UX writing style guide.
+
+### Missing data points
+
+Indicate missing data with a special visual marker (like a different color or shape) to highlight the gaps without connecting them.
diff --git a/packages/documentation/docs/controls/charts/pie-chart.md b/packages/documentation/docs/controls/charts/pie-chart.md
index 80177fd310..61d720ffa1 100644
--- a/packages/documentation/docs/controls/charts/pie-chart.md
+++ b/packages/documentation/docs/controls/charts/pie-chart.md
@@ -1,23 +1,26 @@
import Playground from '@site/src/components/PlaygroundV3';
-# Pie chart
+# Pie charts
-## Examples
+Pie charts display data using a circular graph. The length of each slice is proportional to the value it represents. Pie charts are commonly used to visualize the parts of a whole and are particularly useful for comparing the relative sizes of different categories.
-### Donut chart
+### Pie chart example
-### Pie chart
+### Donut charts
+
+Donut charts are a variation of pie charts that have a hole in the center. Donut charts are often used to display the same information as a pie chart, but additional information can be displayed in the center of the chart.
+
diff --git a/packages/documentation/docs/controls/charts/special-chart.md b/packages/documentation/docs/controls/charts/special-chart.md
index aad0242907..6213b74da8 100644
--- a/packages/documentation/docs/controls/charts/special-chart.md
+++ b/packages/documentation/docs/controls/charts/special-chart.md
@@ -5,19 +5,12 @@ import Playground from '@site/src/components/PlaygroundV3';
# Functionalities
-ECharts offers a wide variety of different chart types and features. Following page deals with some more special chart types and chart features, which might become handy in some use cases.
-
-
-## Examples
-
+ECharts offer a wide variety of different chart types and features. The following page deals with some of the more special chart types and features.
### Interactive toolbox
-Apache ECharts offers a versatile toolbox that enables users to interact with and manipulate charts effectively.
-By default, the toolbox appears in the top right corner of the chart.
-You can customize this toolbox using the `toolbox` option within the option object.
+Apache ECharts offers a versatile toolbox that enables users to interact with and manipulate charts effectively. By default, the toolbox appears in the top right corner of the chart. It includes various interactive tools like download, zoom, zoom reset and restore. Each has been designed to enhance the user experience. You can customize this toolbox using the `toolbox` option within the option object.
-The toolbox includes various interactive tools (like download, zoom, change type), each designed to enhance the user experience.
-Below is an example demonstrating some of the most commonly used tools and how to configure them to suit your needs.
+Below is an example demonstrating some of the most commonly used tools and how you can configure them.
### Advanced zoom and pan
In addition to the toolbox, ECharts provides zoom and pan functionality for a more interactive chart experience.
-Users can zoom in and out using the mouse wheel, and pan the chart by clicking and dragging.
-These features offer a seamless way to explore detailed data within the chart.
+Users can zoom in and out using the mouse wheel, and pan the chart by clicking and dragging. These advanced features offer a seamless way to explore detailed data within the chart.