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 DAG page #11943

Merged
merged 3 commits into from
Oct 20, 2023

Conversation

agilgur5
Copy link
Member

@agilgur5 agilgur5 commented Oct 4, 2023

Motivation

started off by just improving the fail fast section, which did not quite line up with the style guide

  • then ended up modifying the rest of the page, as it was fairly short

Modifications

  • structural improvements:

    • add a heading for the "Fail Fast" section
      • it has its own paragraph, should have its own section
        • especially as it's a bit aside from just using DAGs; it's a specific feature (and was added as such)
    • add a section with a link to "Enhanced Depends" because this is a very commonly asked user question
      • we direct users to the "Enhanced Depends" feature already when they ask if they can do something; let's get ahead of that by directing in DAG page already
    • add a link to the steps page when it is mentioned
  • clarifications:

    • "This" -> "DAGs" -- be more specific about the subject for clarity
    • "steps", "nodes" -> "tasks" -- that is what the field is called in a DAG template
  • stylistic changes:

    • 1 markdown line per sentence
    • use present tense where possible, per k8s style guide
    • significantly simplify the fail fast section, per k8s style guide
    • no need to have fail fast in backticks as it's not a code reference
      • do add backticks around the failFast field, as that's the specific keyword used in the YAML
        • remove "FailFast" from .spelling as words with backticks are ignored
  • add the 1 sentence per line preference that I mentioned above and use myself to the docs styleguide

    • this way, diffs to sentences are limited to a specific line, not an entire paragraph
    • often there are no conventions for how to split lines, so a paragraph can be on multiple lines, some of which have multiple sentences, others of which are one sentence, and others which are not even a full sentence
      • we don't need to follow line width code conventions for markdown as it is prose, not code
      • we do need some convention for consistency
    • a paragraph on a single line is a bit harder to read in an editor in monospace font etc as well, IMO

Verification

make docs-spellcheck passes

started off by just improving the fail fast section, which did not quite line up with the [style guide](https://argoproj.github.io/argo-workflows/doc-changes/)
- then ended up modifying the rest of the page, as it was fairly short

- structural improvements:
  - add a heading for the "Fail Fast" section
    - it has its own paragraph, should have its own section
      - especially as it's a bit aside from just using DAGs; it's a specific feature (and was added as such)
  - add a section with a link to "Enhanced Depends" because this is a very commonly asked user question
    - we direct users to the "Enhanced Depends" feature already when they ask if they can do something; let's get ahead of that by directing in DAG page already
  - add a link to the steps page when it is mentioned

- clarifications:
  - "This" -> "DAGs" -- be more specific about the subject for clarity
  - "steps", "nodes" -> "tasks" -- that is what the field is called in a DAG template

- stylistic changes:
  - 1 markdown line per sentence
  - [use present tense](https://kubernetes.io/docs/contribute/style/style-guide/#use-present-tense) where possible, per k8s style guide
  - significantly simplify the fail fast section, [per k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#use-simple-and-direct-language)
  - no need to have fail fast in backticks as it's not a code reference
    - do add backticks around the `failFast` _field_, as that's the specific keyword used in the YAML
      - remove "FailFast" from `.spelling` as words with backticks are ignored

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
- diffs to sentences are limited to a specific line, not an entire paragraph
- often there are no conventions for how to split lines, so a paragraph can be on multiple lines, some of which have multiple sentences, others of which are one sentence, and others which are not even a full sentence
  - we don't need to follow line width code conventions for markdown as it is prose, not code
  - we do need _some_ convention for consistency
- a paragraph on a single line is a bit harder to read in an editor in monospace font etc as well, IMO

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
@agilgur5 agilgur5 added the area/docs Incorrect, missing, or mistakes in docs label Oct 4, 2023
Signed-off-by: Anton Gilgur <4970083+agilgur5@users.noreply.github.com>
@agilgur5
Copy link
Member Author

Fixed merge conflict with .spelling changes from #11814 (two removals were right next to each other, both are removed now)

@terrytangyuan terrytangyuan merged commit 0220f4c into argoproj:master Oct 20, 2023
16 checks passed
@agilgur5 agilgur5 deleted the docs-dag-copy-edit branch October 20, 2023 02:40
agilgur5 added a commit that referenced this pull request May 4, 2024
Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
Signed-off-by: Anton Gilgur <4970083+agilgur5@users.noreply.github.com>
(cherry picked from commit 0220f4c)
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
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants