Refactor README: improve clarity, add keyboard shortcuts, and expand documentation

[BrettKinny]

Summary

Comprehensive restructuring and expansion of the README to improve clarity, usability, and technical documentation. The changes focus on making the documentation more accessible to both users and developers while providing better technical details about how the application works.

Key Changes

• Improved tagline and introduction: Simplified language ("for the terminal" instead of "for the terminal heads"), clarified feature descriptions with better punctuation and grammar

• Reorganized comparison table: Streamlined the Traditional OPC Clients vs opcilloscope comparison with more concise entries and proper markdown escaping

• Consolidated use cases: Moved use cases from a separate section into a single inline sentence for better flow

• Enhanced feature descriptions:

  • Clarified that monitoring uses "OPC UA pub/sub, not polling"
  • Added scope window details (30 s sliding window)
  • Added new "Trend Plot" feature description
  • Emphasized CSV recording captures "zero data loss"
  • Specified config file format (.cfg JSON files)
  • Simplified theme description (Dark default, Light option)

• Added new "How signal sampling works" collapsible section: Detailed explanation of the pub/sub mechanism with ASCII diagram, comparison table of update rates, and technical details about data capture vs rendering decoupling

• Added comprehensive keyboard shortcuts table: New section documenting all major keyboard commands (Tab, Enter, Delete, Space, S, T, W, +/-, Ctrl+O/S, Ctrl+R, ?)

• Improved installation section:

  • Changed "Install (User)" to just "Install"
  • Added collapsible "Linux dependency: ICU libraries" section with distro-specific installation commands
  • Moved uninstall instructions into a collapsible details section
  • Simplified "Then to run" language

• Cleaned up developer quickstart: Removed redundant comments, improved formatting

• Removed redundant content: Eliminated duplicate demo image captions and taglines, removed multiple horizontal dividers for cleaner structure

• Improved footer: Simplified license statement and attribution, removed redundant line breaks

Notable Details

All changes are documentation-only (README.md). The restructuring maintains all original information while improving organization, readability, and user experience through better visual hierarchy and collapsible sections for advanced topics.

https://claude.ai/code/session_017mtMAWLUuP46pdNY8zqM5G

[claude]

Code Review: README Refactoring

Thank you for this comprehensive documentation improvement! This PR significantly enhances the README's clarity and usability. Here's my detailed review:

---

✅ Strengths

1. Excellent Information Architecture

• Collapsible sections for advanced topics (signal sampling, ICU dependencies, uninstall) reduce cognitive load while keeping information accessible
• Keyboard shortcuts table is a fantastic addition — makes the tool immediately more approachable
• Streamlined comparison table with proper markdown escaping (curl \| bash) fixes rendering issues
• Consolidated use cases into a single line improves flow and reduces repetition

2. Technical Accuracy & Clarity

• ✅ "OPC UA pub/sub, not polling" — technically correct terminology
• ✅ "30 s sliding window" — specific, measurable detail
• ✅ "Zero data loss" claim is backed by implementation (queue-based CSV recording)
• ✅ Signal sampling explanation with ASCII diagram is excellent for understanding the architecture
• ✅ "~40 MB RAM" removes ambiguous "Resource-hungry" claim with concrete metric

3. User Experience Improvements

• Removing "for the terminal heads" makes it more professional and inclusive
• "Then run:" is more direct than "Then to run:"
• Removed redundant horizontal rules and duplicate captions
• Better visual hierarchy with strategic use of <details> blocks

---

🔍 Suggestions for Improvement

1. Keyboard Shortcuts Table - Context Missing

The keyboard shortcuts table doesn't indicate which view/context each shortcut applies to. This could confuse users when a key doesn't work.

Suggestion: Add a "Context" column or group by section:

| Key | Action | Context |
|-----|--------|---------|
| `Tab` | Cycle between panes | Global |
| `Enter` | Subscribe to selected node | Address Space View |
| `Delete` | Unsubscribe from selected variable | Monitored Variables View |
| `Space` | Toggle selection / pause scope | Monitored Variables / Scope View |

Or group them:

**Global:**
- `Tab` — Cycle between panes
- `Ctrl+O` / `Ctrl+S` — Open / save configuration
- `?` — Help

**Address Space View:**
- `Enter` — Subscribe to selected node

**Monitored Variables View:**
- `Delete` — Unsubscribe
- `Space` — Toggle selection
- `S` — Open scope with selected variables

This matches the format in CLAUDE.md:1140-1179, which groups shortcuts by context.

---

2. Signal Sampling Deep Dive - Minor Technical Clarification

Line 51 states: "opcilloscope does not poll your OPC UA server. The server pushes value updates using OPC UA's built-in publish/subscribe mechanism."

Minor clarification: The term "publish/subscribe" in OPC UA typically refers to PubSub (Part 14 of the spec), which is different from the Subscription mechanism used here (Part 4). The implementation uses OPC UA Subscriptions with MonitoredItems, not PubSub.

Suggested wording:

opcilloscope does **not** poll your OPC UA server. The server *pushes* value updates using OPC UA's Subscription mechanism (MonitoredItems with notifications).

However, the current wording is acceptable for a general audience — just noting this for technical precision.

---

3. Install Section - Missing Platform Prerequisites

The "Install" section doesn't mention that .NET runtime is bundled in the releases (if it is) or required separately. Users might wonder if they need to install .NET separately.

Recommendation: Add a brief note:

## Install

Pre-compiled binaries include the .NET runtime — no additional dependencies required (except ICU on Linux).

---

4. Keyboard Shortcuts - Incomplete Coverage

The shortcuts table is missing some keys documented in CLAUDE.md:

Missing from README but in CLAUDE.md:

• F5 — Refresh address space tree (CLAUDE.md:1155)
• Ctrl+Shift+S — Save configuration as (CLAUDE.md:1147)
• Ctrl+Q — Quit (CLAUDE.md:1148)
• R — Reset to auto-scale in scope view (CLAUDE.md:1171)

Suggestion: Add these to the table or create a "See ? for complete list" note.

---

5. Use Cases - Grammar Nitpick

Line 25: "recording (export to CSV for reports)"

The parenthetical repeats "recording" → "export" which is slightly redundant. Consider:

-**Use cases:** commissioning (verify PLC tags), troubleshooting (live values during fault diagnosis), integration testing (validate OPC UA server configs), recording (export to CSV for reports).
+**Use cases:** commissioning (verify PLC tags), troubleshooting (live values during fault diagnosis), integration testing (validate OPC UA server configs), data logging (export to CSV for analysis).

---

🎯 Overall Assessment

Category	Rating	Notes
Code Quality	N/A	Documentation-only change
Clarity	⭐⭐⭐⭐⭐	Significant improvement in readability
Accuracy	⭐⭐⭐⭐½	Minor terminology clarification suggested
User Experience	⭐⭐⭐⭐⭐	Collapsible sections, keyboard shortcuts table excellent
Completeness	⭐⭐⭐⭐	Missing a few shortcuts, but covers essentials

---

✅ Approval Recommendation

Approve with minor suggestions. This is a high-quality documentation improvement that makes the project significantly more accessible. The suggestions above are optional enhancements — none are blockers.

Merge-ready after addressing (optional):

1. Add context/grouping to keyboard shortcuts table
2. Consider adding missing shortcuts from CLAUDE.md

---

📝 Additional Notes

• No code changes → no test coverage concerns
• No security implications
• No performance impact
• Follows project naming conventions (opcilloscope lowercase, consistent branding)
• Maintains consistency with CLAUDE.md project documentation

Great work! 🚀