[docs][data grid] Audit and revise the Pro column docs

docs/data/data-grid/column-ordering/column-ordering.md

@@ -1,36 +1,42 @@
 ---
-title: Data Grid - Column ordering
+title: Data Grid - Drag-and-drop column reordering
 ---
 
-# Data Grid - Column ordering [<span class="plan-pro"></span>](/x/introduction/licensing/#pro-plan 'Pro plan')
+# Data Grid - Drag-and-drop column reordering [<span class="plan-pro"></span>](/x/introduction/licensing/#pro-plan 'Pro plan')
 
-<p class="description">Drag and drop your columns to reorder them.</p>
+<p class="description">The Data Grid Pro lets users drag and drop columns to reorder them.</p>
 
-:::warning
-There is [a known issue with Firefox v129](https://github.com/mui/mui-x/issues/14263) that impacts this feature.
-Reordering does not work on that specific version of Firefox because the value for `event.dataTransfer` is `null` which results in an error.
+Columns are organized according to the order in which they're provided in the `columns` array.
+By default, the Data Grid Pro lets users reorder columns by dragging and dropping the header cells—give it a try in the demo below:
 
-You must upgrade to Firefox v130 or higher to avoid this issue.
-:::
+{{"demo": "ColumnOrderingGrid.js", "bg": "inline"}}
 
-By default, columns are ordered according to the order they are included in the `columns` array.
+## Column reordering events
 
-By default, Data Grid Pro allows all column reordering by dragging the header cells and moving them left or right.
+Column reordering emits the following events:
 
-{{"demo": "ColumnOrderingGrid.js", "bg": "inline"}}
+- `columnHeaderDragStart`: emitted when the user starts dragging the header cell.
+- `columnHeaderDragEnter`: emitted when the cursor enters another header cell while dragging.
+- `columnHeaderDragOver`: emitted when the user drags a header cell over another header cell.
+- `columnHeaderDragEnd`: emitted when the user stops dragging the header cell.
 
-To disable reordering on all columns, set the prop `disableColumnReorder={true}`.
+## Disabling column reordering
 
-To disable reordering in a specific column, set the `disableReorder` property to true in the `GridColDef` of the respective column.
+Drag-and-drop column reordering is enabled by default on the Data Grid Pro, but you can disable it for some or all columns.
 
-{{"demo": "ColumnOrderingDisabledGrid.js", "bg": "inline"}}
+### For all columns
 
-In addition, column reordering emits the following events that can be imported:
+To disable reordering for all columns, set the `disableColumnReorder` prop to `true`:
 
-- `columnHeaderDragStart`: emitted when dragging of a header cell starts.
-- `columnHeaderDragEnter`: emitted when the cursor enters another header cell while dragging.
-- `columnHeaderDragOver`: emitted when dragging a header cell over another header cell.
-- `columnHeaderDragEnd`: emitted when dragging of a header cell stops.
+```tsx
+<DataGridPro disableColumnReorder />
+```
+
+### For specific columns
+
+To disable reordering for a specific column, set the `disableReorder` property to `true` in the column's `GridColDef`, as shown below:
+
+{{"demo": "ColumnOrderingDisabledGrid.js", "bg": "inline"}}
 
 ## API
 

docs/data/data-grid/column-pinning/column-pinning.md

@@ -4,21 +4,23 @@ title: Data Grid - Column pinning
 
 # Data Grid - Column pinning [<span class="plan-pro"></span>](/x/introduction/licensing/#pro-plan 'Pro plan')
 
-<p class="description">Pin columns to keep them visible at all time.</p>
+<p class="description">Implement pinning to keep columns in the Data Grid visible at all times.</p>
 
-Pinned (or frozen, locked, or sticky) columns are columns that are visible at all time while the user scrolls the Data Grid horizontally.
-They can be pinned either to the left or right side and cannot be reordered.
+Pinned columns (also known as sticky, frozen, and locked) are visible at all times while scrolling the Data Grid horizontally.
+Users can access this feature through the column menu to pin and unpin columns to either the left or right side.
+Pinned columns cannot be [reordered](/x/react-data-grid/column-ordering/), except by unpinning and repinning.
 
-To pin a column, there are a few ways:
+## Implementing column pinning
 
-- Using the `initialState` prop
-- [Controlling](#controlling-the-pinned-columns) the `pinnedColumns` and `onPinnedColumnsChange` props
-- Dedicated buttons in the column menu
-- Accessing the [imperative](#apiref) API
+The Data Grid Pro provides column pinning to end users by default, and there are several different tools you can use to modify the experience to meet your needs:
 
-## Initializing the pinned columns
+- The `initialState` prop – for pinning during initialization
+- The `pinnedColumns` and `onPinnedColumnsChange` props – for more control over pinning
+- The imperative `apiRef` API – for fully custom solutions
 
-To set pinned columns via `initialState`, pass an object with the following shape to this prop:
+### Column pinning on initialization
+
+To set pinned columns when the Data Grid is initialized, pass a value to the `pinnedColumns` property of the `initialState` prop with the following shape:
 
 ```ts
 interface GridPinnedColumnFields {
@@ -27,73 +29,75 @@ interface GridPinnedColumnFields {
 }
 ```
 
-The following demos illustrates how this approach works:
+The demo below illustrates how this works:
 
 {{"demo": "BasicColumnPinning.js", "bg": "inline"}}
 
-:::info
-The column pinning feature can be completely disabled with `disableColumnPinning`.
-
-```tsx
-<DataGridPro disableColumnPinning />
-```
-
-:::
-
 :::warning
 You may encounter issues if the sum of the widths of the pinned columns is larger than the width of the Grid.
 Make sure that the Data Grid can properly accommodate these columns at a minimum.
 :::
 
-## Controlling the pinned columns
+### Controlled column pinning
 
-While the `initialState` prop only works for setting pinned columns during the initialization, the `pinnedColumns` prop allows you to modify which columns are pinned at any time.
-The value passed to it follows the same shape from the previous approach.
-Use it together with `onPinnedColumnsChange` to know when a column is pinned or unpinned.
+The `pinnedColumns` prop gives you more granular control over how the user can interact with the pinning feature.
+To implement this prop, pass an object to it with the same shape as that outlined in [the `initialState` section above](#column-pinning-on-initialization).
+Use it together with `onPinnedColumnsChange` to track when columns are pinned and unpinned, as shown in the demo below:
 
 {{"demo": "ControlPinnedColumns.js", "bg": "inline"}}
 
-## Disable column pinning
+## Disabling column pinning
+
+Column pinning is enabled by default on the Data Grid Pro, but you can disable it for some or all columns.
 
 ### For all columns
 
-Column pinning is enabled by default, but you can easily disable this feature by setting the `disableColumnPinning` prop.
+To disable pinning for all columns, set the `disableColumnPinning` prop to `true`:
 
 ```tsx
 <DataGridPro disableColumnPinning />
 ```
 
-### For some columns
+### For specific columns
 
-To disable the pinning of a single column, set the `pinnable` property in `GridColDef` to `false`.
+To disable pinning for a specific column, set the `pinnable` property to `false` in the column's `GridColDef`, as shown below:
 
 ```tsx
-<DataGridPro columns={[{ field: 'id', pinnable: false }]} /> // Default is `true`.
+<DataGridPro columns={[{ field: 'id', pinnable: false }]} /> // Default is `true`
 ```
 
-### Pin non-pinnable columns programmatically
+### Remove pinning from the column menu
 
-It may be desirable to allow one or more columns to be pinned or unpinned programmatically that cannot be pinned or unpinned on the UI (that is columns for which prop `disableColumnPinning = true` or `colDef.pinnable = false`).
-This can be done in one of the following ways.
+An alternative option for disabling pinning actions is to remove them from the user interface, which can be done in one of two ways:
 
-- (A) Initializing the pinned columns
-- (B) Controlling the pinned columns
-- (C) Using the API method `setPinnedColumns` to set the pinned columns
+1. Use the column menu API to hide the pinning actions. See [Column menu—Hiding a menu item](/x/react-data-grid/column-menu/#hiding-a-menu-item) for details.
+2. Use the [`disableColumnMenu` prop](/x/react-data-grid/column-menu/#disable-column-menu) to completely remove the column menu altogether.
+
+## Pinning non-pinnable columns programmatically
+
+When [pinning is disabled](#disabling-column-pinning) in the UI for some or all columns (via `disableColumnPinning` or `colDef.pinnable`), it's still possible to implement it programmatically.
+You can do this in one of three ways:
+
+1. Initialized pinning with `initialState`
+2. Controlled pinning with `pinnedColumns`
+3. Using the [`setPinnedColumns()` method](#apiref)
+
+The code snippets below illustrate these three approaches:
 
 ```tsx
-// (A) Initializing the pinning
+// 1. Initialized pinning
 <DataGridPro
   disableColumnPinning
   initialState={{ pinnedColumns: { left: ['name'] } }}
 />
 
-// (B) Controlling the pinned columns
+// 2. Controlled pinning
 <DataGridPro
   disableColumnPinning
   pinnedColumns={{ left: ['name'] }}
 />
 
-// (C) Using the API method `setPinnedColumns` to set the pinned columns
+// 3. Using the `setPinnedColumns()` method
 <React.Fragment>
   <DataGridPro disableColumnPinning />
   <Button onClick={() => apiRef.current.setPinnedColumns({ left: ['name'] })}>
@@ -102,32 +106,22 @@ This can be done in one of the following ways.
 </React.Fragment>
 ```
 
-The following demo uses method (A) to initialize the state of the pinned columns which pins a column `name` although the pinning feature is disabled.
+In the following demo, pinning is disabled but the Grid is initialized with the **Name** column pinned to the left:
 
 {{"demo": "DisableColumnPinningButtons.js", "bg": "inline"}}
 
-:::info
-Another alternate option to disable pinning actions on the UI is to disable the pinning options in the column menu in one of the following ways.
-
-1. Use [`disableColumnMenu` prop](/x/react-data-grid/column-menu/#disable-column-menu) to completely disable the column menu.
-2. Use column menu API to hide the pinning options in the column menu. See [Column Menu - Hiding a menu item](/x/react-data-grid/column-menu/#hiding-a-menu-item) for more details.
-
-:::
-
 ## Pinning autogenerated columns
 
-Some features add columns to the grid.
-Pin those columns by providing their field names to the list of pinned columns.
-
-To pin the row reordering column added when using `rowReordering` and checkbox column added when using `checkboxSelection`, add `GRID_REORDER_COL_DEF.field` and `GRID_CHECKBOX_SELECTION_COL_DEF.field` to the list of pinned columns.
+Certain features (such as [checkbox selection](/x/react-data-grid/row-selection/#checkbox-selection) and [row reordering](/x/react-data-grid/row-ordering/)) add autogenerated columns in the Data Grid.
+You can pin these by adding `GRID_CHECKBOX_SELECTION_COL_DEF.field` and `GRID_REORDER_COL_DEF.field`, respectively, to the list of pinned columns, as shown in the demo below:
 
 {{"demo": "ColumnPinningAutogeneratedColumns.js", "bg": "inline"}}
 
-## Usage with dynamic row height
+## Pinning columns with dynamic row height
 
-You can have both pinned columns and [dynamic row height](/x/react-data-grid/row-height/#dynamic-row-height) enabled at the same time.
-However, if the rows change their content after the initial calculation, you may need to trigger a manual recalculation to avoid incorrect measurements.
-You can do this by calling `apiRef.current.resetRowHeights()` every time that the content changes.
+The Data Grid supports use cases involving both column pinning and [dynamic row height](/x/react-data-grid/row-height/#dynamic-row-height).
+However, if row contents change after the initial calculation, you may need to trigger a manual recalculation to avoid incorrect measurements.
+You can do this by calling `apiRef.current.resetRowHeights()` whenever the content changes.
 
 The demo below contains an example of both features enabled:
 

docs/data/data-grid/column-spanning/column-spanning.md

@@ -28,7 +28,7 @@ To avoid a confusing grid layout, consider disabling the following features for
 - [filtering](/x/react-data-grid/filtering/#disable-the-filters)
 - [column reorder](/x/react-data-grid/column-ordering/)
 - [hiding columns](/x/react-data-grid/column-visibility/)
-- [column pinning](/x/react-data-grid/column-pinning/#disable-column-pinning)
+- [column pinning](/x/react-data-grid/column-pinning/#disabling-column-pinning)
 
 :::
 

docs/data/pages.ts

@@ -52,7 +52,11 @@ const pages: MuiPage[] = [
               { pathname: '/x/react-data-grid/column-menu' },
               { pathname: '/x/react-data-grid/column-spanning' },
               { pathname: '/x/react-data-grid/column-groups' },
-              { pathname: '/x/react-data-grid/column-ordering', plan: 'pro' },
+              {
+                pathname: '/x/react-data-grid/column-ordering',
+                title: 'Column reordering',
+                plan: 'pro',
+              },
               { pathname: '/x/react-data-grid/column-pinning', plan: 'pro' },
               { pathname: '/x/react-data-grid/column-recipes', title: 'Recipes' },
             ],