Polish documentation: Low priority improvements

- Standardize heading capitalization to sentence case for consistency
- Convert state management caveats to table format for better scannability
- Add 'Quick testing workflow' summary box with TL;DR examples
- Add version information to README tools table (v1.2.0 for fasterdata-tuning)
- Include release note about save/restore state management feature

Author: ShawnMcKee

docs/perfsonar/tools_scripts/README.md

@@ -2,16 +2,18 @@
 
 This directory contains helper scripts for perfSONAR deployment, configuration, and tuning.
 
-## Available Tools
-
-| Tool | Purpose | Documentation |
-|------|---------|---------------|
-| **fasterdata-tuning.sh** | Host & NIC tuning (ESnet Fasterdata) | [Fasterdata Tuning Guide](fasterdata-tuning.md) |
-| **perfSONAR-pbr-nm.sh** | Multi-NIC policy-based routing | [Multiple NIC Guidance](../multiple-nic-guidance.md) |
-| **perfSONAR-update-lsregistration.sh** | LS registration management | [LS Registration Tools](README-lsregistration.md) |
-| **perfSONAR-auto-enroll-psconfig.sh** | Automatic pSConfig enrollment | [Installation Guides](../../personas/quick-deploy/landing.md) |
-| **install_tools_scripts.sh** | Bulk installer for all scripts | [Installation](#installation) |
-| **install-systemd-service.sh** | Container auto-start on boot | [Container Management](#container-management) |
+## Available tools
+
+| Tool | Version | Purpose | Documentation |
+|------|---------|---------|---------------|
+| **fasterdata-tuning.sh** | v1.2.0 | Host & NIC tuning (ESnet Fasterdata) | [Fasterdata Tuning Guide](fasterdata-tuning.md) |
+| **perfSONAR-pbr-nm.sh** | — | Multi-NIC policy-based routing | [Multiple NIC Guidance](../multiple-nic-guidance.md) |
+| **perfSONAR-update-lsregistration.sh** | — | LS registration management | [LS Registration Tools](README-lsregistration.md) |
+| **perfSONAR-auto-enroll-psconfig.sh** | — | Automatic pSConfig enrollment | [Installation Guides](../../personas/quick-deploy/landing.md) |
+| **install_tools_scripts.sh** | — | Bulk installer for all scripts | [Installation](#installation) |
+| **install-systemd-service.sh** | — | Container auto-start on boot | [Container Management](#container-management) |
+
+**Latest Updates**: v1.2.0 (Dec 2025) adds save/restore state management to fasterdata-tuning.sh
 
 ---
 

docs/perfsonar/tools_scripts/fasterdata-tuning.md

@@ -30,7 +30,7 @@ sudo curl -L -o /usr/local/bin/fasterdata-tuning.sh https://osg-htc.org/networki
 sudo chmod +x /usr/local/bin/fasterdata-tuning.sh
 ```
 
-## Verify the Checksum (Optional)
+## Verify the checksum (optional)
 
 To verify script integrity, compare the downloaded file with the provided SHA256 checksum:
 
@@ -84,7 +84,7 @@ tc qdisc show dev <iface>
 cat /proc/cmdline | grep -E "iommu=pt|intel_iommu=on|amd_iommu=on"
 ```
 
-## Security & Safety
+## Security & safety
 
 - Always test in a staging environment first. Use `--mode audit` to review before applying.
 
@@ -141,10 +141,32 @@ sudo /usr/local/bin/fasterdata-tuning.sh --mode apply --apply-iommu --dry-run
 sudo /usr/local/bin/fasterdata-tuning.sh --mode apply --apply-iommu --iommu-args "intel_iommu=on iommu=pt" --yes
 ```
 
-## State Management: Save & Restore Configurations
+## State management: Save and restore configurationsns
 
 **NEW in v1.2.0**: The script now supports saving and restoring system state for testing different tuning configurations.
 
+### Quick testing workflow
+
+**TL;DR**: Save baseline → Apply tuning → Test → Restore → Compare
+
+```bash
+# Save baseline state
+sudo /usr/local/bin/fasterdata-tuning.sh --save-state --label baseline
+
+# Apply tuning
+sudo /usr/local/bin/fasterdata-tuning.sh --mode apply --target measurement --yes
+
+# Run your performance tests here (iperf3, perfSONAR tests, etc.)
+
+# Restore baseline
+sudo /usr/local/bin/fasterdata-tuning.sh --restore-state baseline --yes
+
+# Compare configurations
+/usr/local/bin/fasterdata-tuning.sh --diff-state baseline
+```
+
+**For detailed step-by-step workflow with multiple tuning profiles, see [Example Performance Testing Workflow](#example-performance-testing-workflow) below.**
+
 ### Why use save/restore?
 
 When testing performance with different tuning configurations, you need to:
@@ -299,33 +321,32 @@ sudo /usr/local/bin/fasterdata-tuning.sh --restore-state baseline --yes
 /usr/local/bin/fasterdata-tuning.sh --mode audit
 ```
 
-### State Management Caveats
-
-**What IS saved/restored:**
-
-- ✅ Sysctl parameters (runtime values)
-- ✅ Configuration files (`/etc/sysctl.d/90-fasterdata.conf`, systemd service)
-- ✅ Per-interface settings (txqueuelen, MTU, ring buffers, offload features, qdisc)
-- ✅ CPU governor (runtime)
-- ✅ SMT state (runtime)
-- ✅ Tuned profile
+### State management caveats
 
-**What is NOT saved/restored:**
+**What is and is not saved/restored:**
 
-- ❌ GRUB kernel command-line parameters (IOMMU, persistent nosmt) - requires reboot
-- ❌ Kernel module parameters
-- ❌ Firewall rules
-- ❌ Network interface creation/deletion
+| Component | Saved/Restored | Notes |
+|-----------|----------------|-------|
+| Sysctl parameters | ✅ Yes | Runtime values (TCP buffers, congestion control, etc.) |
+| Configuration files | ✅ Yes | `/etc/sysctl.d/90-fasterdata.conf`, systemd services |
+| Per-interface settings | ✅ Yes | txqueuelen, MTU, ring buffers, offload features, qdisc |
+| CPU governor | ✅ Yes | Runtime setting |
+| SMT state | ✅ Yes | Runtime setting |
+| Tuned profile | ✅ Yes | Active profile |
+| GRUB kernel cmdline | ❌ No | Requires reboot (IOMMU, persistent nosmt); not suitable for testing cycles |
+| Kernel module parameters | ❌ No | Out of scope |
+| Firewall rules | ❌ No | Not modified by this script |
+| Network interfaces | ❌ No | Interface creation/deletion not supported |
 
-**Limitations:**
+**Important limitations:**
 
 1. **Hardware-dependent**: Ring buffer sizes are limited by NIC hardware; restoration may fail if hardware doesn't support saved values
 2. **Hostname-specific**: Restoring a state from a different hostname will trigger a warning but proceed
 3. **NetworkManager**: Connection modifications may cause brief network interruptions
 4. **Side effects**: Changing tuned profile may modify additional sysctls not tracked by this script
 5. **Requires python3**: State save/restore operations require python3 for JSON processing
 
-### State File Format
+### State file format
 
 State files are stored as JSON in `/var/lib/fasterdata-tuning/saved-states/` with the following structure: