Mixed root-level option pipeline with a nested command pipeline is confusing
- 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
Assessment
This issue has not been assessed yet.