This diff updates our doc so that we are explicit about certain steps being required rather than optional, as was previously implied by using "you can."
Details
Details
- Reviewers
atul varun - Group Reviewers
Restricted Owners Package (Owns No Changed Paths) - Commits
- rCOMMb3b267eab769: [docs] Remove 'you can' instance from non-optional steps
Verify Markdown looks as expected.
Diff Detail
Diff Detail
- Repository
- rCOMM Comm
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
Comment Actions
I think the intent was to avoid an imperative or ordering tone. Probably want something like Please run the following: instead of Run this command:
Then again, I'm terrible at diction.
Comment Actions
I think the intent was to avoid an imperative or ordering tone.
I believe the intent here was to remove "you can" because it could give the impression that a step is optional.
(@adar might be helpful to include a Linear link or something in the future to provide that context)
Comment Actions
My $0.02 is that we might not need to include "run this command" at all in the docs; I'd imagine most of our target audience would get that text in a markdown code block implies for the user to execute a given command.
NBD, just from what I've seen in some other docs before, I do understand how being explicit removes any possible ambiguity.
Comment Actions
I believe the intent here was to remove "you can" because it could give the impression that a step is optional.
Then to @adar credit, the steps are not optional.
Comment Actions
My $0.02 is that we might not need to include "run this command" at all in the docs; I'd imagine most of our target audience would get that text in a markdown code block implies for the user to execute a given command.
NBD, just from what I've seen in some other docs before, I do understand how being explicit removes any possible ambiguity.
Yeah personally agree, but defer to the docs folks since they have pretty specific language preferences