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 webHDFS page #11516

Merged
merged 2 commits into from
Aug 14, 2023

Conversation

agilgur5
Copy link
Member

@agilgur5 agilgur5 commented Aug 3, 2023

Motivation

Am making a few larger copy-edits now that I'm (very) familiar with the docs; this was one of the smaller ones that I managed to complete. This page is particularly self-encompassing, so works well as a first. It's also a great example page but had a bit of verbosity to it -- it's now considerably more concise.

Primarily in order to follow the k8s docs style guide and simplify docs to make them more approachable to all audiences

Modifications

Stylistic changes

  • use more direct language, per k8s style guide

    • "Using webHDFS protocol via HTTP artifacts" -> "webHDFS via HTTP artifacts"
    • "In order to use [...] we will make use of" -> "You can use"
    • "HTTP URL" -> "URL"
      • also consistently use the term "query paramter" instead of "HTTP URL parameter", which is ambiguous (path params, query params, etc)
    • "need to append" -> "append"
    • "This results in the following URL" -> "The result is"
    • "Now, when run, the workflow will" -> "The workflow will"
    • "There are some additional fields that can be set" -> "Additional fields can be set"
    • "In order to declare" -> "To delcare"
    • "need to change [...] to" -> "instead use"
    • "where we want the [...] to be stored" -> "your desired location"
    • "want to store the artifact under" -> "artifact will be stored at"
    • "also supply the optional overwrite [...] to allow [...]" -> "can overwrite [...] with"
    • "may want to provide some authentication option" -> "may want to use authentication"
    • "a usage of [...] can be realized by supplying" -> "can be used via"
    • several other more complex / multi-sentence simplifications
  • use in-line links, per k8s style guide

  • consistently use "the full webHDFS example" when referring to the main example (instead of differing descriptions for the same example)

  • remove "all you need", "little change", "only", etc per k8s style guide

  • address the reader as "you", per k8s style guide

  • replace Latin phrases, per k8s style guide

  • move "Additional fields" sentence to after the in-line example, as the example does not use those and it is a side note

  • comment out elipses in code blocks so that they are more copyable / valid syntax

  • use an infobox instead of "Limitation:" to be consistent with the rest of the docs

  • minor grammatical fixes

    • extra commas, extra articles, etc

Semantic changes

  • add links to HTTP artifacts and the overwrite parameter
    • remove note about overwrite depending on provider. the (newly linked) docs specify that it defaults to false
  • clarify the difference between Hadoop native auth and provider dependent auth
    • specify that tokens are used via the delegation query param, per the linked docs

Verification

Checked that all new links work, page renders.

Future Work

  1. This page really doesn't fit under "Use Cases", which is intended for broad proposes, such as "Machine Learning", not a very specific example. This might fit better under "Patterns".
    • I was going to just move it, but it will require a redirect as its URL is currently under use-cases/.
      • and redirects are not built into mkdocs, they require a plugin, so that requires an extra dep and configuration etc
        • redirects are good to have in general though, so I will probably add this in a separate PR

agilgur5 and others added 2 commits August 3, 2023 18:12
Stylistic changes:
- use more direct language, per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#use-simple-and-direct-language)
  - "Using webHDFS protocol via HTTP artifacts" -> "webHDFS via HTTP artifacts"
  - "In order to use [...] we will make use of" -> "You can use"
  - "HTTP URL" -> "URL"
    - also consistently use the term "query paramter" instead of "HTTP URL parameter", which is ambiguous (path params, query params, etc)
  - "need to append" -> "append"
  - "This results in the following URL" -> "The result is"
  - "Now, when run, the workflow will" -> "The workflow will"
  - "There are some additional fields that can be set" -> "Additional fields can be set"
  - "In order to declare" -> "To delcare"
  - "need to change [...] to" -> "instead use"
  - "where we want the [...] to be stored" -> "your desired location"
  - "want to store the artifact under" -> "artifact will be stored at"
  - "also supply the optional overwrite [...] to allow [...]" -> "can overwrite [...] with"
  - "may want to provide some authentication option" -> "may want to use authentication"
  - "a usage of [...] can be realized by supplying" -> "can be used via"
  - several other more complex / multi-sentence simplifications

- use in-line links, per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#links)
- consistently use "the full webHDFS example" when referring to the main example (instead of differing descriptions for the same example)

- remove "all you need", "little change", "only", etc per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#avoid-words-that-assume-a-specific-level-of-understanding)
- address the reader as "you", per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#address-the-reader-as-you)
- replace Latin phrases, per [k8s style guide](https://kubernetes.io/docs/contribute/style/style-guide/#avoid-latin-phrases)

- move "Additional fields" sentence to after the in-line example, as the example does not use those and it is a side note
- comment out elipses in code blocks so that they are more copyable / valid syntax
- use an infobox instead of "**Limitation**:" to be consistent with the rest of the docs

- minor grammatical fixes
  - extra commas, extra articles, etc

Semantic changes:
- add links to HTTP artifacts and the `overwrite` parameter
  - remove note about `overwrite` depending on provider. the (newly linked) docs specify that it defaults to `false`
- clarify the difference between Hadoop native auth and provider dependent auth
  - specify that tokens are used via the `delegation` query param, per the linked docs

Signed-off-by: Anton Gilgur <agilgur5@gmail.com>
@terrytangyuan terrytangyuan enabled auto-merge (squash) August 14, 2023 14:27
@terrytangyuan terrytangyuan merged commit 6a1c7ef into argoproj:master Aug 14, 2023
23 checks passed
@agilgur5 agilgur5 deleted the docs-improve-webhdfs branch August 17, 2023 19:04
@agilgur5 agilgur5 added area/docs Incorrect, missing, or mistakes in docs area/artifacts S3/GCP/OSS/Git/HDFS etc labels Sep 13, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/artifacts S3/GCP/OSS/Git/HDFS etc area/docs Incorrect, missing, or mistakes in docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants