Skip to content

usability: use cross-platform paths in example docs #170

@changliu2

Description

@changliu2

Reporter perspective

As a first-time user on macOS/Linux/WSL, I tried to copy commands from the example docs. Several commands and table entries use Windows backslashes (\), which are not portable in Unix-like shells. Forward slashes work in PowerShell too, so the examples can be made cross-platform without losing Windows support.

Evidence

Backslash paths in customer-facing example docs:

  • examples/README.md:20
    assert-eval run --config examples\travel_planner_langgraph\eval_config.yaml
  • examples/README.md:32
    assert-eval init --model azure/gpt-5.4-mini --from examples\travel_planner_langgraph\eval_config.yaml
  • examples/README.md:42
    • incident_triage_agent\eval_config_baseline.yaml
    • incident_triage_agent\README.md
    • docs\case-study-incident-triage-joint.md
  • examples/README.md:47
    assert-eval run --config examples\science_research_agent\eval_config.yaml
    
  • examples/incident_triage_agent/README.md:193-194
    assert-eval run --config examples\incident_triage_agent\eval_config_baseline.yaml
    assert-eval run --config examples\incident_triage_agent\eval_config_guarded.yaml
  • examples/incident_triage_agent/README.md:200-201
    assert-eval run --config examples\incident_triage_agent\eval_config_naive_prompt.yaml
    assert-eval run --config examples\incident_triage_agent\eval_config_guarded_gepa.yaml
  • examples/incident_triage_agent/README.md:217
    python scripts\render_trade_off.py --suite incident-triage-agent-v1

PowerShell-specific activation paths like .\.venv\Scripts\Activate.ps1 are OK when kept in PowerShell-only setup blocks. This issue is about repo-relative paths in commands/tables.

Recommended fix

Use forward slashes in command examples and path literals:

examples/travel_planner_langgraph/eval_config.yaml
examples/incident_triage_agent/eval_config_baseline.yaml
scripts/render_trade_off.py

Then spot-check copy-paste in PowerShell and a Unix shell.

Slice rollups

Found by slice 1, slice 4, and slice 5:

  • C:\Users\changliu2\.copilot\session-state\3714f9ab-3680-4990-a750-a80c932203f2\files\usability-slice-1-rollup.md
  • C:\Users\changliu2\.copilot\session-state\3714f9ab-3680-4990-a750-a80c932203f2\files\usability-slice-4-rollup.md
  • C:\Users\changliu2\.copilot\session-state\3714f9ab-3680-4990-a750-a80c932203f2\files\usability-slice-5-rollup.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationshould-fixConfusing or visibly rough but not launch-blocking

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions