Zowe Explorer for VS Code Extension Readme Revisions

[adam-wolfe]

Summary: The Zowe Explorer for VS Code README should be reviewed by a doc writer and condensed to limit duplication of Zowe Docs content. The introduction should be rewritten with input from the Onboarding Squad to improve clarity and ensure that the messaging aligns with expectations.

Is your request for enhancement related to a problem? Please describe.

This issue refers to documentation that is maintained in the zowe-explorer-vscode and docs-site repos.

The first thing people see when they search for Zowe Explorer in VS Code Marketplace is the README, which is maintained within the zowe-explorer-vscode repository. While the README has been updated periodically to ensure that the information is up-to-date, I think there should be a more comprehensive review/rewrite of the content.

I see a few doc-specific issues with the Zowe Explorer VS Code extension's README:

• The introduction (which is effectively a copy of content in ze-install from Zowe Docs):
  • Talks about modernizing the mainframe experience, which is ambiguous. It would be better to say what Zowe Explorer does, e.g.: Zowe Explorer enables mainframe developers to work remotely with z/OS data sets, USS files, and jobs in Visual Studio Code.
  • Lists features in a way that is repetitive and challenging to read.
    • Starting every item with "Enabling you to", "Providing a", or "Letting you" is unnecessarily repetitive and should be avoided.
    • The first two listed features should be combined to say that you can do x, y, z with data sets and USS files.
    • The third listed feature: "Providing a more streamlined way to access data sets, uss files, and jobs." repeats the same information from the first two listed features and makes a vague claim about being more streamlined.
    • Lacks appropriate trademark characters after the first instances of Zowe, Open Mainframe Project, and Linux Foundation.
• The readme contains a lot of tutorials and animated gifs, however the information only covers some aspects of profile management and use of the data sets tree (excluding the USS and jobs trees). Most of this information is available in docs.zowe.org, though some of it is not. We should reduce the amount of information that we are including in the README.md to a level that helps users get started and avoids duplicating too much content from Zowe Docs.
  • The current level of content duplication makes it challenging to maintain the readme and keep content in sync with Zowe Docs.
  • We could take inspiration from Zowe Explorer for IntelliJ (https://plugins.jetbrains.com/plugin/18688-zowe-explorer) which only provides a functional description of the plug-in. However, I think we would want to provide a bit more guidance in terms of initial setup and team config.

Describe the solution you'd like

We should re-evaluate the information we include in the Zowe Explorer for VS Code README to:

• Confirm that our messaging is appropriate
• Improve quality, clarity, and consistency
• Reduce duplication of Zowe Docs content within the extension README by limiting the amount of tutorials/use cases

I began to make some revisions in zowe-explorer-vscode PR-2988, including a proposed rewrite of the introduction.

However, since this is an issue with documentation in both the Zowe Docs and the Zowe Explorer for VS Code repository, it seemed prudent to bring this to the Docs Squad.

Related doc pages

This request applies to:

• https://marketplace.visualstudio.com/items?itemName=Zowe.vscode-extension-for-zowe
  • Which is generated from https://github.com/zowe/zowe-explorer-vscode/blob/main/packages/zowe-explorer/README.md
• https://docs.zowe.org/stable/user-guide/ze-install - The intro from the Zowe Explorer readme appears to have been taken from this page in Zowe Docs.

Additional context

The Zowe project manages a number of VS Code extensions, IntelliJ plug-ins, and Zowe CLI plug-ins, each with their own READMEs/one-pagers that are published to npmjs, VS Code Marketplace, JetBrains Marketplace, etc.

In many cases, these READMEs are managed by the squad that maintains the extension/plug-in and contain information that is not always reviewed by a doc writer. In the future, it might make sense to reach out to the squads to have a doc writer review these READMEs.