-
Notifications
You must be signed in to change notification settings - Fork 3.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: full copy-edit of enhanced depends
page
#13110
Merged
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
larger style changes: - heavily simplify several sentences and paragraphs, per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#use-simple-and-direct-language) - remove unnecessary "Introduction" section -- just introduce it - describe how `depends` improves on `dependencies`, instead of explaining the history and limitations - same description, but substantially more concise and no longer dated - remove some redundant short descriptions like "or failed" that are described better and in more detail almost immediately after - simplify the task result table by combining "Description" and "Meaning" - previously "Description" was redundant, repeating the result - remove dated statements like "new" etc, per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#avoid-statements-that-will-soon-be-out-of-date) - Also, "Previous to version 2.8" has a grammatical error, seems incorrect (directly above says `v2.9`), and is not consistent with our existing versioning usage, which is the `> v2.9 and after` that already exists above - "the user" -> "you", per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#address-the-reader-as-you) - similarly, use active voice, per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#use-active-voice) - and use a more consistent tense as well - consistently use "results"; do not use "status" sometimes to mean the same thing -- inconsitency is confusing - similarly, use the word "unspecified" instead of "omitted" when referring to a task with no result specified -- `.Omitted` is an existing term here already - elaborate why this exists; it's not just conveninence, it's for compat with `dependencies` - elaborate why `continueOn` is not available either; it can be substituted by `.Failed` in `depends` smaller style modifications: - remove modifiers like "easy", per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#avoid-words-that-assume-a-specific-level-of-understanding) - similarly remove modifiers like "complex" and "full"; those modifiers felt misleading given that the boolean logic only has 3 operators - remove Latin abbreviations like "etc", per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#avoid-latin-phrases) - prefer 1 sentence per line of markdown, per [style guide](https://argo-workflows.readthedocs.io/en/release-3.5/doc-changes/) Signed-off-by: Anton Gilgur <[email protected]>
agilgur5
added
area/docs
Incorrect, missing, or mistakes in docs
area/templates/dag
labels
May 29, 2024
Signed-off-by: Anton Gilgur <[email protected]>
Signed-off-by: Anton Gilgur <[email protected]>
Signed-off-by: Anton Gilgur <[email protected]>
juliev0
approved these changes
Jun 17, 2024
yulin-li
pushed a commit
to yulin-li/argo-workflows
that referenced
this pull request
Jun 17, 2024
Signed-off-by: Anton Gilgur <[email protected]> Signed-off-by: Yulin Li <[email protected]>
agilgur5
added a commit
that referenced
this pull request
Jun 17, 2024
Signed-off-by: Anton Gilgur <[email protected]> (cherry picked from commit 669d4a4)
agilgur5
added a commit
that referenced
this pull request
Jun 17, 2024
Signed-off-by: Anton Gilgur <[email protected]> (cherry picked from commit 669d4a4)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Labels
area/docs
Incorrect, missing, or mistakes in docs
area/templates/dag
prioritized-review
For members of the Sustainability Effort
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Follow-up to #13087 (review) and my other full page copy-edits of docs
Fixes #8693 (comment)
Addresses the first question of #10363 as well
Motivation
Heavily simplify the page, elaborate on some details, and use consistent, up-to-date style
Modifications
larger style changes:
depends
improves ondependencies
, instead of explaining the history and limitationsv2.9
), and is not consistent with our existing versioning usage (c.f. docs: consistently use "> v{version} and after" #12581), which is the> v2.9 and after
that already exists aboveconsistently use "results"; do not use "status" sometimes to mean the same thing -- inconsistency is confusing
.Omitted
is an existing term here alreadydependencies
elaborate why
continueOn
is not available either; it can be substituted by.Failed
independs
smaller style modifications:
Verification
make docs
passes