-
Notifications
You must be signed in to change notification settings - Fork 3.1k
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
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
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>
jmeridth
approved these changes
Oct 17, 2023
juliev0
approved these changes
Oct 19, 2023
Signed-off-by: Anton Gilgur <4970083+agilgur5@users.noreply.github.com>
Fixed merge conflict with |
terrytangyuan
approved these changes
Oct 20, 2023
8 tasks
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
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.
Motivation
started off by just improving the fail fast section, which did not quite line up with the style guide
Modifications
structural improvements:
clarifications:
stylistic changes:
failFast
field, as that's the specific keyword used in the YAML.spelling
as words with backticks are ignoredadd the 1 sentence per line preference that I mentioned above and use myself to the docs styleguide
Verification
make docs-spellcheck
passes