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

[Vladimir-Bosnjak]

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