Skip to content
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 4 commits into from
Jun 17, 2024

Conversation

agilgur5
Copy link

@agilgur5 agilgur5 commented May 29, 2024

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:

  • heavily simplify several sentences and paragraphs, per k8s style guide
    • 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
  • consistently use "results"; do not use "status" sometimes to mean the same thing -- inconsistency 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 for convenience, 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
    • 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
  • prefer 1 sentence per line of markdown, per style guide

Verification

  1. make docs passes
  2. See rendered markdown

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 agilgur5 added area/docs Incorrect, missing, or mistakes in docs area/templates/dag labels May 29, 2024
@agilgur5 agilgur5 requested a review from Joibel May 29, 2024 09:01
Anton Gilgur added 2 commits May 29, 2024 05:06
Signed-off-by: Anton Gilgur <[email protected]>
Signed-off-by: Anton Gilgur <[email protected]>
@agilgur5 agilgur5 added this to the v3.5.x patches milestone May 29, 2024
@agilgur5 agilgur5 added the prioritized-review For members of the Sustainability Effort label Jun 10, 2024
@juliev0 juliev0 merged commit 669d4a4 into argoproj:main Jun 17, 2024
17 checks passed
yulin-li pushed a commit to yulin-li/argo-workflows that referenced this pull request Jun 17, 2024
@agilgur5 agilgur5 deleted the docs-depends-copy-edit branch June 17, 2024 12:45
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
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants