[Part 3] Update documentation content for all charts

change/@fluentui-react-charting-8c7e2a0d-fb53-4e19-9c69-3cddec6c7b24.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Updating documentation content",
+  "packageName": "@fluentui/react-charting",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-charting/README.md

@@ -67,33 +67,75 @@ The library has a wide variety of tests to ensure quality of the library.
 The tests range from component tests, unit tests, visual regression tests, accessibility tests, integration tests and manual tests.
 The test automations aim to ensure over 90% code coverage across the library.
 
-Further details available in the wiki
+Further details available in the [wiki](https://aka.ms/fluentChartingWiki)
 
 Run `yarn test` from within the package to run all the tests.
 
 ## Accessibility
 
 Our charts have elaborate accessibility support. The charts are WCAG 2.1 MAS C compliant for accessibility.
 
-More details are covered in the wiki.
+More details are covered in the [wiki](https://aka.ms/fluentChartingWiki).
 
 ## Performance
 
 Performance is a key success criteria for the charting library.
 Performance is measured and has been improved for the following scenarios.
-|**S No**| **Scenario** | **Lighthouse Score** |
-|:------:|:------------------------------------------------: | :----------------------: |
-| 1. | 1 LineChart of 1 series with 30,000 datapoints | 79.2 |
-| 2. | 6 LineCharts of 1 series with 100 datapoints each | 98.8 |
-| 3. | 18 LineCharts of 1 series with 5 datapoints | 98 |
-| 4. | 50 Linecharts of 1 Series with 10 datapoints each | 89.6 |
-| 5. | 1 Linechart of 2 series with 500 datapoints each | 98.6 |
-| 6. |10 Linecharts of 1 series with 1000 datapoints each| 94.4 |
-| 7. | 1 Areachart with 30,000 datapoints | 49 |
-| 8. | 6 Areacharts of 1 series with 100 datapoints each | 95.4 |
-| 9. |18 Areacharts of 1 series with 5 data points each | 96.8 |
-
-More details are covered in the wiki.
+
+<table>
+  <tr>
+    <th>S No</th>
+    <th>Scenario</th>
+    <th>Lighthouse Score</th>
+  </tr>
+<tr>
+    <td>1.</td>
+    <td>1 LineChart of 1 series with 30,000 datapoints</td>
+    <td>79.2</td>
+</tr>
+<tr>
+    <td>2.</td>
+    <td>6 LineCharts of 1 series with 100 datapoints each</td>
+    <td>98.8</td>
+</tr>
+<tr>
+    <td>3.</td>
+    <td>18 LineCharts of 1 series with 5 datapoints</td>
+    <td>98</td>
+</tr>
+<tr>
+    <td>4.</td>
+    <td>50 Linecharts of 1 Series with 10 datapoints each</td>
+    <td>89.6</td>
+</tr>
+<tr>
+    <td>5.</td>
+    <td>1 Linechart of 2 series with 500 datapoints each</td>
+    <td>98.6</td>
+</tr>
+<tr>
+    <td>6.</td>
+    <td>10 Linecharts of 1 series with 1000 datapoints each</td>
+    <td>94.4</td>
+</tr>
+<tr>
+    <td>7.</td>
+    <td>1 Areachart with 30,000 datapoints</td>
+    <td>49</td>
+</tr>
+<tr>
+    <td>8.</td>
+    <td>6 Areacharts of 1 series with 100 datapoints each</td>
+    <td>95.4</td>
+</tr>
+<tr>
+    <td>9.</td>
+    <td>18 Areacharts of 1 series with 5 data points each</td>
+    <td>96.8</td>
+</tr>
+<table>
+
+More details are covered in the [wiki](https://aka.ms/fluentChartingWiki).
 
 ## Versioning and changelog
 

packages/react-examples/src/react-charting/AreaChart/AreaChart.doc.tsx

@@ -52,6 +52,8 @@ export const AreaChartPageProps: IDocPageProps = {
   ],
   overview: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartOverview.md'),
   bestPractices: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartBestPractices.md'),
+  dos: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartDos.md'),
+  donts: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartDonts.md'),
   isHeaderVisible: true,
   isFeedbackVisible: true,
 };

packages/react-examples/src/react-charting/AreaChart/AreaChartPage.tsx

@@ -75,6 +75,16 @@ export class AreaChart extends React.Component<IComponentDemoPageProps, {}> {
             {require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartBestPractices.md')}
           </Markdown>
         }
+        dos={
+          <Markdown>
+            {require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartDos.md')}
+          </Markdown>
+        }
+        donts={
+          <Markdown>
+            {require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/AreaChart/docs/AreaChartDonts.md')}
+          </Markdown>
+        }
       />
     );
   }

packages/react-examples/src/react-charting/AreaChart/docs/AreaChartBestPractices.md

@@ -1,3 +1,36 @@
+### Layout
+
+Padding on the left and right of the chart is determined by the x-axis labels - it should start and end at or close to the first and last tick mark. The minimum padding is 8px.
+
+Currently we support stacked area charts only.
+
 ### Content
 
-AreaChart best practices content placeholder.
+- **Area line** An area line represents a set of values from the same data set. Each line takes on a new swatch in the data visualization library to distinguish it from others. 2px wide. There is no rounding of joints to avoid data misrepresentation.
+- **Area fill** Uses the same color family as the area line, but applies a 50% opacity.
+
+**Note:** the implemented stacked area components use transparency fills, but we cannot apply transparency in the Figma guidance
+
+### Accessibility
+
+- Users "Enter" into the graph and can use both arrow and tab keys to navigate through.
+- The first tab stop will stop on the graph and give a description of what type of graph it is.
+- Each section of the graph is readable via screen readers. The user can navigate through the entire area plot by using Left and Right arrow keys.
+
+### Interaction
+
+The area chart is a highly performant visual. It uses a path-based rendering mechanism to render the area component. On hovering, the nearest x datapoint is identified and the corresponding point is hovered.
+
+### Customizing the chart
+
+- **Stacked area chart**
+  In stacked area chart, two or more data series are stacked vertically. It helps in easy comparison across different dimensions. The callout on hover for stacked chart displays multiple values from the stack. The callout can be customized to show single values or stacked values. Refer to the props `onRenderCalloutPerDataPoint` and `onRenderCalloutPerStack` using which custom content for the callout can be defined.
+- **Custom accessibility**
+  Area chart provides a bunch of props to enable custom accessibility messages. Use `xAxisCalloutAccessibilityData` and `callOutAccessibilityData` to configure x axis and y axis accessibility messages, respectively.
+
+#### Axis localization
+
+The chart axes support 2 ways of localization.
+
+1. JavaScript provided inbuilt localization for numeric and date axis. Specify the culture and `dateLocalizeOptions` for date axis to define target localization. Refer the [Javascript localization guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleDateString) for usage.
+2. Custom locale definition: The consumer of the library can specify a custom locale definition as supported by d3 [like this](https://github.com/d3/d3-time-format/blob/main/locale/en-US.json). The date axis will use the date range and the multiformat specified in the definition to determine the correct labels to show in the ticks. For example - If the date range is in days, then the axis will show hourly ticks. If the date range spans across months, then the axis will show months in tick labels and so on. Specify the custom locale definition in the `timeFormatLocale` prop. Refer to the Custom Locale Date Axis example in line chart for sample usage.

packages/react-examples/src/react-charting/AreaChart/docs/AreaChartDonts.md

@@ -0,0 +1,3 @@
+- Prefer line charts to plot trends.
+- No more than 9 lines on a chart; fewer are better.
+- Do not remove axis titles unless it is clear to the user what is being visualized.

packages/react-examples/src/react-charting/AreaChart/docs/AreaChartDos.md

@@ -0,0 +1 @@
+- Remain consistent with one chart style if there are multiple instances of it on a page rather than using area and line charts interchangeably.

packages/react-examples/src/react-charting/AreaChart/docs/AreaChartOverview.md

@@ -1,43 +1,5 @@
-<div>
-  <p>
-    Area charts depict a time-series relationship. But unlike line charts, they can also visually represent
-    volume. Information is graphed on two axes, using data points connected by line segments. The area between
-    the axis and this line is commonly emphasized with color or shading for legibility. Most often area charts
-    compare two or more categories. The area chart is a highly performant visual. It uses a path based
-    rendering mechanism to render the area component. On hovering, the nearest x datapoint is identified and
-    the corresponding point is hovered.
-  </p>
-  <h3>Area chart variants</h3>
-  <h4>Stacked area chart</h4>
-  <p>
-    In stacked area chart, two or more data series are stacked vertically. It helps in easy comparison across
-    different dimensions. The callout on hover for stacked chart displays multiple values from the stack. The
-    callout can be customized to show single values or stacked values. Refer to the props
-    <code>onRenderCalloutPerDataPoint and onRenderCalloutPerStack</code> using which custom content for the
-    callout can be defined.
-  </p>
-  <h4>Custom accessibility</h4>
-  <p>
-    Area chart provides a bunch of props to enable custom accessibility messages. Use
-    <code>xAxisCalloutAccessibilityData</code>
-    and <code>callOutAccessibilityData</code> to configure x axis and y axis accessibility messages
-    respectively.
-  </p>
-  <h4>Date Axis localization</h4>
-  <p>
-    The axes support 2 ways of localization. <br />
-    1. Javascript provided inbuilt localization for numeric and date axis. Specify the culture and
-    dateLocalizeOptions for date axis to define target localization. Refer the
-    <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleDateString">
-      Javascript localization guide
-    </a>
-    for usage. <br />
-    2. Custom locale definition: The consumer of the library can specify a custom locale definition as
-    supported by d3 <a href="https://github.com/d3/d3-time-format/blob/main/locale/en-US.json">like this</a>.
-    The date axis will use the date range and the multiformat specified in the definition to determine the
-    correct labels to show in the ticks. For example - If the date range is in days then the axis will show
-    hourly ticks. If the date range spans across months then the axis will show months in tick labels and so
-    on. Specify the custom locale definition in the <code>timeFormatLocale</code> prop. Refer to the Custom
-    Locale Date Axis example in line chart for sample usage.
-  </p>
-</div>
+Area charts are graphical representations of data that display quantitative data points connected by lines and filled with colors to create a visual representation of trends and patterns. The area between the line and the x-axis is colored, which helps in emphasizing the cumulative total or the overall magnitude of the data. They are a slight variation of single line charts, and generally can be used interchangeably.
+
+Stacked area charts are great at communicating how multiple data series relate to the total value. It illustrates how each series compares to the other in their contributions to the total. The baseline is moving in stacked area charts, rather than sharing a common baseline in overlapping areas.
+
+Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library.

packages/react-examples/src/react-charting/DonutChart/DonutChart.CustomAccessibility.Example.tsx

@@ -18,7 +18,7 @@ export class DonutChartCustomAccessibilityExample extends React.Component<IDonut
       {
         legend: 'first',
         data: 20000,
-        color: getColorFromToken(DataVizPalette.disabled),
+        color: getColorFromToken(DataVizPalette.color16),
         xAxisCalloutData: '2020/04/30',
         callOutAccessibilityData: { ariaLabel: 'Pia chart 1 of 2 2020/04/30' },
       },

packages/react-examples/src/react-charting/DonutChart/DonutChart.doc.tsx

@@ -44,6 +44,8 @@ export const DonutChartPageProps: IDocPageProps = {
   ],
   overview: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartOverview.md'),
   bestPractices: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartBestPractices.md'),
+  dos: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartDos.md'),
+  donts: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartDonts.md'),
   isHeaderVisible: true,
   isFeedbackVisible: true,
 };

packages/react-examples/src/react-charting/DonutChart/DonutChartPage.tsx

@@ -62,6 +62,16 @@ export class DonutChartPage extends React.Component<IComponentDemoPageProps, {}>
             {require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartBestPractices.md')}
           </Markdown>
         }
+        dos={
+          <Markdown>
+            {require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartDos.md')}
+          </Markdown>
+        }
+        donts={
+          <Markdown>
+            {require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/DonutChart/docs/DonutChartDonts.md')}
+          </Markdown>
+        }
       />
     );
   }

packages/react-examples/src/react-charting/DonutChart/docs/DonutChartBestPractices.md

@@ -1,3 +1,19 @@
+### Layout
+
+- The donut chart’s behavior is simple in application. The data is ordered from largest to smallest in clockwise direction and users can single out individual segments for clarity.
+- For high cardinality scenarios where the slices are very small, they can be grouped together to form a bigger slice to improve readability.
+- The chart is centered in the available screen space. The default chart diameter is 140px and bar width is 16px. This matches the width of bars in bar charts to achieve balanced scale. The size can be adjusted with responsive chart behavior, where the size of the chart and bar diameter grows proportionally in units of 4px.
+- Always try to balance the visual weight of the bars in relationship to the rest of the app.
+- Segments are separated by a 2px gap to maximize readability. Segment labels should be always displayed for easier chart comprehension.
+- Minimum padding around the chart is 16px. It also applies to the version with labels to accommodate space for labels. There is a 2px space between the chart and the label. The label is centered in relationship to the slice it describes. That can be offset if an overlap happens between 2 labels.
+
 ### Content
 
-DonutChart best practices content placeholder.
+- The donut chart consists of segments arranged clockwise from large to small. The total circle equates to 100% of the data. The segments can use custom formatting, but all values must add up to 100%. Tiny segments may be grouped and shown visually as 'Others'.
+- The label string inside the donut should be concise and contain numerical information with limited or no explanation.
+
+### Accessibility
+
+- Users "Enter" into the graph and can use both arrowing and tabbing to navigate through.
+- The first tab stop will stop on the graph and give a description of what type of graph it is.
+- Each segment can define its own accessibility label to help the user understand the data better.

packages/react-examples/src/react-charting/DonutChart/docs/DonutChartDonts.md

@@ -0,0 +1 @@
+- Don't overuse donuts charts. They require a lot of space on the page and using more than one next to each other dilutes the intended message.

packages/react-examples/src/react-charting/DonutChart/docs/DonutChartDos.md

@@ -0,0 +1,2 @@
+- For scenarios with lots of categories, consider changing the type of graph to a stacked horizontal bar chart.
+- We recommend donut charts over pie charts as they are more readable.

packages/react-examples/src/react-charting/DonutChart/docs/DonutChartOverview.md

@@ -1,17 +1,3 @@
-<div>
-  <p>
-    Donut charts show a percentage of a whole. They are circular statistical graphics divided into slices to
-    illustrate numerical proportion. Donut charts have an empty center where a numerical value can be shown.
-  </p>
-  <p>
-    The arc length of each data set in a donut is proportional to the quantity it represents, which can also
-    be expressed as a horizontal bar chart.
-  </p>
-  <p>
-    <strong>Note:</strong> Donut Charts typically represent two data points. Representing more data in a
-    circular chart (as seen in the second example) is known by the MADS team as a Pie Chart.
-  </p>
-  <p>
-    The arc labels are hidden by default. Set the <code>hideLabels</code> prop to false to show them.
-  </p>
-</div>
+Donut charts are used to show proportion, which expresses a partial value in comparison to a total value. These types of charts are best to show percentage of individual parts in comparison to a whole, where the change over time is not important to visualize. They are circular statistical graphics divided into slices to illustrate numerical proportion.
+
+Refer to this [Readme](https://github.com/microsoft/fluentui/blob/master/packages/react-charting/README.md) on how to start using the `@fluentui/react-charting` library.

packages/react-examples/src/react-charting/GaugeChart/GaugeChart.doc.tsx

@@ -28,6 +28,8 @@ export const GaugeChartPageProps: IDocPageProps = {
   ],
   overview: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartOverview.md'),
   bestPractices: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartBestPractices.md'),
+  dos: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDos.md'),
+  donts: require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDonts.md'),
   isHeaderVisible: true,
   isFeedbackVisible: true,
 };

packages/react-examples/src/react-charting/GaugeChart/GaugeChartPage.tsx

@@ -50,6 +50,16 @@ export class GaugeChartPage extends React.Component<IComponentDemoPageProps, {}>
             {require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartBestPractices.md')}
           </Markdown>
         }
+        dos={
+          <Markdown>
+            {require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDos.md')}
+          </Markdown>
+        }
+        donts={
+          <Markdown>
+            {require<string>('!raw-loader?esModule=false!@fluentui/react-examples/src/react-charting/GaugeChart/docs/GaugeChartDonts.md')}
+          </Markdown>
+        }
       />
     );
   }