dotnet / dotnet/docs

Mixed root-level option pipeline with a nested command pipeline is confusing

Open
#52,980 0 comments 0 reactions 1 assignee Claimed by @gewarren View on GitHub
:watch: Not Triaged dotnet-fundamentals/svc
Dominant language
No language data
Stars
4.8k
Forks
6.1k
Avg merge
19h 10m
Merged PRs (30d)
268

Description

### Type of issue

Other (describe below)

### Description

The tutorial mixes a root-level option pipeline with a nested command pipeline in the same example:

`fileOption` is attached directly to rootCommand via `rootCommand.Options.Add(fileOption)`
`readCommand` is attached indirectly via `rootCommand -> quotesCommand -> readCommand`

I felt it created an unclear mental model as a learner, because both constructs participate in the eventual invocation path, but they are introduced with different attachment mechanisms and different semantics. One is a named option attached to the root command, while the other is a nested command path built through subcommands. I didn't trust my mental model for a while.

As presented, the example does not sufficiently explain:

- why --file belongs at the root rather than to read
- why the user should think of quotes read as one execution path, while --file is a root-scoped option that also feeds into that path
- what conceptual problem is being solved by showing both structures together

Why mixing two competing pipelines?

- a root-scoped option pipeline
- a nested command pipeline

That is especially confusing because the sample does not first isolate and explain command hierarchy, option scope and why a recursive root option would be appropriate (or wouldn't).

Suggested documentation improvement:
Separate these topics into distinct examples first, one for nested commands and one for root-scoped recursive options.

I favor separation over mixing (with additional explanation) because `Command` and is introduced as a new way and it deserves its own chapter.

### Page URL

https://learn.microsoft.com/en-us/dotnet/standard/commandline/get-started-tutorial

### Content source URL

https://github.com/dotnet/docs/blob/main/docs/standard/commandline/get-started-tutorial.md

### Document Version Independent Id

fa160b1d-66ed-8c5d-37cd-b7e02443e9f1

### Platform Id

0f144444-1ce3-cdf7-87a6-c659d44e08d3

### Article author

@gewarren

### Metadata

* ID: 7705dc41-7297-0807-7e9c-2e6548c26b84
* PlatformId: 0f144444-1ce3-cdf7-87a6-c659d44e08d3
* Service: **dotnet-fundamentals**

[Related Issues](https://github.com/dotnet/docs/issues?q=is%3Aissue+is%3Aopen+fa160b1d-66ed-8c5d-37cd-b7e02443e9f1)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.