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

updates to sec cred doc based on feedback #3350

Merged
merged 1 commit into from
Jan 10, 2024

Conversation

anaxceron
Copy link
Collaborator

Describe your pull request here: Minor changes based on review feedback

List the file(s) included in this PR: cli-using-team-managing-credential-security.md, cli-using-using-team-profiles.md

After creating the PR, follow the instructions in the comments.

Signed-off-by: anaxceron <[email protected]>
@anaxceron anaxceron added area: cli This issue is related to Zowe Command Line Interface (CLI) release: V2 Zowe V2 content review: sme Needs review by an SME labels Jan 9, 2024
@anaxceron anaxceron self-assigned this Jan 9, 2024
@anaxceron anaxceron requested a review from adam-wolfe January 9, 2024 22:54
Copy link

github-actions bot commented Jan 9, 2024

😺 Thank you for creating this PR! To publish your content to Zowe Docs, follow these steps.

  • Add the label review: sme if an SME needs to check your content.
  • Identify your content topic with a label. (Examples: area: apiml, area: cli, area: install and config, etc.)
  • Specify the major Zowe release(s) for your content. (Examples: release: V1, release: V2, release: V3)
    • If adding content that needs to be removed from V3 documentation, add the V3 N/A tag.
  • Link any Doc Issues related to this PR.
  • Fix broken links found in your content areas.
  • Notify the SME to review this PR (if applicable).
  • Merge to the master branch if your PR updates content that is on the live site. Merge to docs-staging if your PR updates content for a future release.

Copy link

github-actions bot commented Jan 9, 2024

😺 Thank you for creating this PR! To publish your content to Zowe Docs, follow these steps.

  • Add the label review: sme if an SME needs to check your content.
  • Identify your content topic with a label. (Examples: area: apiml, area: cli, area: install and config, etc.)
  • Specify the major Zowe release(s) for your content. (Examples: release: V1, release: V2, release: V3)
    • If adding content that needs to be removed from V3 documentation, add the V3 N/A tag.
  • Link any Doc Issues related to this PR.
  • Fix broken links found in your content areas.
  • Notify the SME to review this PR (if applicable).
  • Merge to the master branch if your PR updates content that is on the live site. Merge to docs-staging if your PR updates content for a future release.

2 similar comments
Copy link

github-actions bot commented Jan 9, 2024

😺 Thank you for creating this PR! To publish your content to Zowe Docs, follow these steps.

  • Add the label review: sme if an SME needs to check your content.
  • Identify your content topic with a label. (Examples: area: apiml, area: cli, area: install and config, etc.)
  • Specify the major Zowe release(s) for your content. (Examples: release: V1, release: V2, release: V3)
    • If adding content that needs to be removed from V3 documentation, add the V3 N/A tag.
  • Link any Doc Issues related to this PR.
  • Fix broken links found in your content areas.
  • Notify the SME to review this PR (if applicable).
  • Merge to the master branch if your PR updates content that is on the live site. Merge to docs-staging if your PR updates content for a future release.

Copy link

github-actions bot commented Jan 9, 2024

😺 Thank you for creating this PR! To publish your content to Zowe Docs, follow these steps.

  • Add the label review: sme if an SME needs to check your content.
  • Identify your content topic with a label. (Examples: area: apiml, area: cli, area: install and config, etc.)
  • Specify the major Zowe release(s) for your content. (Examples: release: V1, release: V2, release: V3)
    • If adding content that needs to be removed from V3 documentation, add the V3 N/A tag.
  • Link any Doc Issues related to this PR.
  • Fix broken links found in your content areas.
  • Notify the SME to review this PR (if applicable).
  • Merge to the master branch if your PR updates content that is on the live site. Merge to docs-staging if your PR updates content for a future release.

@anaxceron anaxceron requested a review from IgorCATech January 9, 2024 22:54
@anaxceron
Copy link
Collaborator Author

anaxceron commented Jan 9, 2024

Made a couple of changes based on feedback below.

Most of these comments related to style, and I chose to follow the style that I feel makes the most sense for the tone and scope of our Zowe CLI documentation.

=====

Review feedback from @IgorCATech:

zowe-glossary.md
Line 94: "Secret storage functionality that is embedded in core Zowe CLI and Zowe Explorer starting from Zowe V2."
Line 98: "Securely stores configured your credentials in the secure vault available on your client operating system. Vault examples: Windows Credential Manager on Microsoft Windows, and Passwords and Keys on Ubuntu Linux."

cli-using-team-managing-credential-security.md
Line 10: Remove the H2
(and just outline the procedure below)
Line 9: "Alternatively, you can create a configuration file and set its secure properties (such as usernames and passwords): "
Line 17: "Initialize a project team configuration file in the current working directory by running the following command:"
Then make a ol (or ul) of the commands mentioned in Lines 20-33. Or just mention that you can run the zowe config init -h command to get info about all sub-commands.
Line 37: Try not to use the pronouns like This or That. It rather confuses the reader. It's better to be specific. For example: "The configuration file stores the username and..."
Line 39: "(Optional) Add extra fields to the secure array:"
Line 55: Similar to Line 17. Also, I don't think you need to list all the sub-commands there. Users can find them in the CLI by issuing "zowe config secure -h".
Line 71: "Prompts request new values for all secure fields that are defined in the configuration file. In most cases, these properties include a username or password, but some users may include other fields, such as a token value or connection properties."
Line 73: I think the whole line is redundant because typically CLI users know how to work with such commands.
Line 75: Our standard is usually "You successfully {accomplished action/result}". In this case, you would have something like "You successfully updated credentials in your config file". Try to match the result with object that you declare at the beginning of the procedure.

cli-using-using-team-profiles.md
Line 24: "Your service profiles can pull information from base profiles so that you can specify a common username and password once." "The base profile can optionally store tokens to connect to Zowe API Mediation Layer, which improves security by enabling Multi-Factor Authentication (MFA) and Single Sign-on (SSO)."
Line 32: Redundant.
Line 46: Redundant.
Line 48: Use the Broadcom tech writing standard to describe the result of the procedure.
LIne 50: "For more information about how to manage secure credentials, see ..."

A little correction for
Line 9: "Alternatively, you can create a configuration file and set its secure properties (such as usernames and passwords): "

Copy link

github-actions bot commented Jan 9, 2024

@github-actions github-actions bot temporarily deployed to pull request January 9, 2024 23:17 Inactive
@IgorCATech
Copy link
Contributor

IgorCATech commented Jan 10, 2024

Unfortunately, I cannot comment in front of Line 73 in the top file.
But I would replace "Press Enter to leave the value unchanged." with "Press Enter to run the command."

Same with the cli-using-using-team-profiles.md file, Line 44 :)

Otherwise, it looks good to me, Ana. Thank you!

@anaxceron
Copy link
Collaborator Author

Unfortunately, I cannot comment in front of Line 73 in the top file. But I would replace "Press Enter to leave the value unchanged." with "Press Enter to run the command."

Same with the cli-using-using-team-profiles.md file, Line 44 :)

Otherwise, it looks good to me, Ana. Thank you!

Leaving unchanged as the Enter is used to leave a field unchanged, which may happen multiple times before the command is issued.

Copy link
Collaborator

@adam-wolfe adam-wolfe left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@anaxceron anaxceron changed the title updates based on feedback updates to sec cred doc based on feedback Jan 10, 2024
@anaxceron anaxceron merged commit f3b5921 into master Jan 10, 2024
20 of 21 checks passed
@anaxceron anaxceron deleted the anax-v2.13-seccredfeedback-cli branch January 10, 2024 18:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area: cli This issue is related to Zowe Command Line Interface (CLI) release: V2 Zowe V2 content review: sme Needs review by an SME
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants