docs: enhance persona pages with playbooks and quick reference

[ShawnMcKee]

Overview

This comprehensive PR enhances all three persona landing pages with complete user journey documentation, adds troubleshooting playbooks for common issues, and provides a quick-reference card for operators.

Changes

1. Enhanced Persona Landing Pages

Quick Deploy (🚀)

• Clear deployment path options: Orchestrated (fast), Manual (custom), Automated (repeatable)
• Time estimates and skill level indicators
• Links to all post-deploy configuration: tuning, PBR, LS registration, security
• Validation and troubleshooting guidance

Troubleshooter (🔧)

• Quick start diagnostics (5-minute triage)
• Diagnostic tools and guides for host, network, and firewall issues
• Common scenarios linked to detailed playbooks
• Clear escalation paths (self-service → site → OSG/WLCG → community)

Researcher (🔭)

• Complete system architecture overview
• Data flow from measurement to visualization
• Dashboard access (Grafana, PSETF, Analytics)
• Programmatic APIs (Elasticsearch, pSConfig)
• Development and contribution guidelines

Created 4 scenario-based playbooks in docs/personas/troubleshoot/playbooks/:

1. container-startup.md — Container won't start or exits immediately

   • Status checks, log review, port verification
   • Common solutions: port conflicts, permission issues, disk space

2. tests-not-running.md — Tests don't execute or produce results

   • pSConfig enrollment verification, pScheduler status
   • Network connectivity tests, firewall checks

3. performance-issues.md — High latency, low bandwidth, slow tests

   • Host tuning audit, NIC settings, network path analysis
   • Bottleneck identification and optimization

4. firewall-issues.md — Firewall blocking, port access problems

   • Required port verification, local and campus firewall diagnostics
   • Campus firewall escalation with required information

Created docs/quick-reference.md — one-page cheat sheet including:

• Essential Contacts — OSG, WLCG, perfSONAR community, local network
• Deployment Quick Start — pre-deployment checklist, orchestrator commands
• Required Ports & Firewall — port table and nftables rules
• Common Commands — container, pScheduler, network, host tuning
• Troubleshooting Checklist — 8-step verification procedure
• Log Locations — where to find container, systemd, host, and kernel logs
• Performance Benchmarks — expected throughput and latency by link speed
• Emergency Procedures — quick fixes for common crisis situations
• Common Issues & Solutions — matrix of issue/fix pairs

4. Navigation Updates (mkdocs.yml)

• Added "Playbooks" subsection under Troubleshooting with 4 playbooks
• Added "Quick Reference" link in Advanced section
• Maintains persona-first navigation hierarchy

Benefits

✅ Complete User Journeys — Each persona page provides a full workflow from start to finish
✅ Self-Service Troubleshooting — Playbooks enable users to resolve common issues without support tickets
✅ Reduced Support Load — Quick reference card answers common questions immediately
✅ Clear Escalation Paths — Guides when and how to escalate to site, OSG, WLCG, or community
✅ Better Content Discovery — All pages cross-link to related resources
✅ Status Transparency — Playbooks marked with completion status (placeholder → work in progress → complete)

Content Status

Content	Status
Persona landing pages	✅ Complete
Playbook structure & quick solutions	✅ Complete
Playbook detailed steps	🚧 In progress (placeholders with structure)
Quick reference card	✅ Complete
Architecture diagrams	📋 Future

Files Changed

• Modified: 3 persona landing pages
• Created: 4 troubleshooting playbooks
• Created: 1 quick-reference card
• Updated: mkdocs.yml navigation

Related Work

Builds on:

• PR docs: reorganize site with persona-first navigation #42: Persona-first homepage reorganization
• PR feat: enable emoji support in markdown #44: Emoji support for better visual hierarchy

Next Steps

• Expand playbook step-by-step details based on community feedback
• Add architecture diagrams to researcher landing page
• Create data-pipeline documentation
• Monitor support requests to identify gaps

Testing

• All markdown files are valid
• Links to existing content verified
• Navigation structure maintained
• Emoji rendering working (via PR feat: enable emoji support in markdown #44)

---

Note: This is a documentation enhancement only — no functional changes to scripts or infrastructure.

[ShawnMcKee]

@copilot docs: perfsonar + persona docs — automated markdown lint fixes and format cleanup

---

This branch automates and applies a large number of safely reversible formatting fixes across the docs/ tree, with particular focus on docs/perfsonar/ and all persona pages. The primary goal is to remove noisy markdownlint (and super-linter) failures while avoiding semantic content changes to instructions and code snippets.

Summary of changes applied:

• Ran and improved scripts/format_markdown.py across docs/ and docs/perfsonar/.
• Added helper scripts: collapse_blank_lines.py, collapse_blank_lines_global.py, fix_inline_fence_lines.py, wrap_long_paragraphs.py, reflow_list_paragraphs.py, join_hyphenated_urls.py, ensure_blank_around_headings_and_fences.py, convert_multiline_imgs.py, wrap_emails_urls.py, disable_md034_in_codeblocks.py, and convert_emphasis_to_heading.py.
• Major fixes include:
  • Collapsed duplicate blank lines (MD012) across many files
  • Ensured blank lines around headings and fences (MD022/MD031/MD032)
  • Added languages to code fences (MD040)
  • Converted inline HTML images to Markdown images where safe (MD033)
  • Wrapped bare URLs & emails outside code blocks in angle brackets (MD034)
  • Joined hyphenated URLs across lines, and normalized bare links in CONTAINER_RESTART_ISSUE.md, documentation/faq.md, tools_scripts/fasterdata-tuning.md.
  • Fixed tables in docs/perfsonar/installation.md (MD055/MD056)
  • Reflowed long list item paragraphs and long paragraphs (MD013) in several files
  • Converted emphasis only lines to headings (MD036)
  • Fixed or added anchors and normalized heading punctuation to reduce MD051

What I validated:

• Ran markdownlint across docs/ and docs/perfsonar/ and iteratively applied fixes until we significantly reduced the overall linter violations.
• Locally validated the linter output and ensured the remaining items were content-sensitive and needed manual review.

Remaining items that require manual review / editorial decision:

• MD051 link fragment in docs/personas/quick-deploy/install-perfsonar-testpoint.md: fixed by normalizing heading slug but the CI slug might differ; I added an explicit anchor to reduce risk (the PR needs a quick review to confirm it's correct).
• MD012 remains in a few release notes and templates where spacing is deliberate for readability — please verify.
• MD013 long lines in a few tool scripts/detailed pages may require editorial choices to wrap commands vs. keeping them on one line.
• MD033 inline HTML with semantic purpose (e.g., tables or span-based formatting) was not removed where it was meaningful.

Recommended reviewer checklist (please review before merging):

• Spot-check the fenced code block examples for accidental content changes (we avoid altering commands; where necessary we used markdownlint disable/enable comments for MD034)
• Confirm any change to heading slugs and link fragments still matches navigation expectations (esp. quick-deploy/install-perfsonar-testpoint.md)
• Verify that any code block or command examples that span multiple lines are still copy/paste-friendly and functionally equivalent to original commands
• Confirm that turning emphasis lines into H3 headings (e.g., metadata lines in osg-debugging-document.md) is acceptable to the writer
• Optionally: run a local mkdocs build (the branch mostly addresses markdown lints and should not break mkdocs, but it's recommended to run mkdocs build or CI to be sure)

If you'd like me to proceed with any editorial choices (e.g., rename duplicate headings, resolve MD013 by wrapping commands vs leaving them intact, or adjust the remaining small items automatically) choose one of the following options in a reply:
A) I’ll apply further automated edits to clear the remaining content-sensitive rules where there’s a clear, safe fix.
B) I’ll prepare a PR body with the full checklist and request maintainers/reviewers to approve the remaining manual fixes.
C) I’ll stop here and leave the remainder for maintainers to apply with the provided guidance.

What I will run next if you pick A:

• Apply programmatic edits for MD013/MD051 limited to non-code lines, update the PR body, and re-run the linter.

Thanks — this PR aims to reduce CI noise while avoiding semantics. Please review the PR description and let me know if you want any of the remaining items changed before merging.

[Copilot]

@ShawnMcKee I've opened a new pull request, #46, to work on those changes. Once the pull request is ready, I'll request review from you.