zowe / docs-site Goto Github PK

In the new website format, file names are displayed as part of the URL to the user. We should check to ensure that file names are descriptive, accurate, and consistent for the content that appears on the page.

I see that https://zowe.github.io/docs-site/user-guide/systemrequirements.html has sections for each component, and each of those sections has its own list of requirements and mixes in bits of config.

Would a single consolidated list of pre-reqs be helpful/possible? For example, the mention of node.js seems like it deserves to be further up front.

Some APIs might have already been dropped (such as the following ones). Need to review the existing doc and make corrections.

• https://zowe.github.io/docs-site/user-guide/usingapis.html#persistent-data-apis
• https://zowe.github.io/docs-site/user-guide/usingapis.html#system-apis
• Dataset - POST /Atlas/api/datasets/{dsn}/{basedsn}
• Z/os System - GET cpu

and also , from a documentation standpoint, are we missing this:

Jobs - get /Atlas/api/jobs/{jobName}/{jobIds}

After installing Zowe under USS I saw ICH408I messages for user logging on for:

• BPX.SMF
• CSFSERV CSFDSV
• CSFSERV CSFOWH
• CSFSERV CSFPKI
• CSFSERV CSFRNGL
• CSFSERV CSFEDH

I suggest these requirements are added to item 5 on https://zowe.github.io/docs-site/user-guide/install-zos.html#installing-the-zowe-runtime-on-z-os

I’ve added a new tile to MVD, showing the API catalog from the mediation layer. You can see a screenshot of it here: zowe/zowe-install-packaging#37 (comment).

I think there needs to be an update to the https://zowe.github.io/docs-site/user-guide/usingzlux.html#using-zlux-application-plug-ins page

The Uninstalling Zowe chapter is not too clear and should be updated with more detailed instructions.
https://zowe.github.io/docs-site/user-guide/uninstall.html

• Uninstalling zLUX

  • What's the name of the zLUX server that should be killed?
  • What does "delete the original folders" mean? Is it the Zowe installation folder? Is there a variable that's set that will help user identify what it is?

• Uninstalling explorer server

  • Step 2. Delete the ZOWESVR member from your system PROCLIB data set.

    • It should be deleting it from whichever PROCLIB dataset ZOWESVR was put in.
    • What if the user does not know which PROCLIB dataset ZOWESVR was put in? Is there a way they could query it?
    • What command should the user issue to delete the ZOWESVR member?

  • 3. Remove RACF definitions

  RDELETE STARTED (ZOWESVR.*)
  SETR RACLIST(STARTED) REFRESH
  REMOVE (userid) GROUP(IZUUSER)
  

  We should add something like "where "userid" is the userid that install Zowe".

  • 4. Delete z/OS USS explorer server directory

    rm -R /var/atlas #* Explorer Server Installation Directory*

  You should ask the user to find out where the explorer server installation directory is rather than just saying to run rm -R /var/atlas. There should be a way the user can find out where the explorer server installation directory is. Do you mean to delete the whole Zowe installation directory (what is in rootDir in zoe-install.yaml) or just the explorer-server directory?

Glossaries are an important resource for our users. They are a source of conceptual information about the project and information about the interrelationships among terms.

This issue is to track the inclusion of a collection of the technical terms and definitions that are used in Zowe.

Issue just to let everyone know I'm aware and working to find the problem.

Curiously the issue does not occur when trying to run in dev, and still appears when using older commits and versions. Will investigate more if it's an environment issue and how to fix.

Detailed procedures have been documented in docs site to instruct users how to install Zowe (on z/OS or on PC). Producing some short videos to demo the install process and insert into our docs site can enhance the user experience.

Collaborate with development to collect input.

(Issue from giza-docs)

Comments from CA content strategist: Add graphic to help the user understand how the three components work together. Add subheadings to break up the content.

To improve, we need to check that we document the following content:

• Product overview
  This topic should be quick and to the point describing the product, business value, features
• Product technical overview
  Provide a high level technical overview of the product that includes discussion of the technology stack and architecture and topology of the product. Think about security when writing about this topic. Use graphics as a visual to communicate the technology stack and the configuration points.
• Concepts
  Key concepts necessary for a user to understand when using the product.

Currently our installation doc for CLI says roughly:

1. Install cli with this command
2. Go to LINK for information about how to install plugins.

We should add an optional step for installing all plugins with a single command directly after the "install CLI" step to make the initial setup easier for users.

• Move Propose content change in GitHub link and the Last Updated indicator to top of the page
  Currently users must scroll down to the end of the page to locate this link if they want to propose file changes in GitHub. Move it to a more obvious location can encourage users to participate in doc improvement and provide feedback.

• Improve the search engine for the docs site.
  Currently, the search only supports scanning headings. We need t provide an enhanced search experience by supporting searching keywords in the whole docs site.

The content in https://zowe.github.io/docs-site/user-guide/usingmvd.html#using-zlux-application-plug-ins is what I would expect to find in "Extending Zlux" section. In "Extending Zowe CLI", we talk about the plug-ins that are available for CLI and how to install them. So this would fit.

So, to address this issue I suggest:

• Take "Using zLUX application plug-ins" section and move the content to "Extending zLUX" under a new heading named "Install Plug-ins to zLUX" or similar.
• Expand on the topic with a procedure - it does not currently tell the user HOW to install a plug-in, it just lists the available plug-ins.
• The content that you have under Extending zLUX right now could be moved to a new section for developers. I think that the User Guide should focus on the end-user of these applications who will be using them in daily work and possibly installing plug-ins to extend the functionality. Then we should have a separate "Develop for Zowe" section that has your content about "creating zLUX plugins and apps" and the other subtopics that describe the framework for developing apps. We have similar content for Imperative Framework that doesn't fit under Tutorials but is still meant for developers. https://github.com/gizafoundation/imperative/wiki/Command-Definition-&-Processing

I think that https://zowe.github.io/docs-site/user-guide/usingmvd.html#zlux-logging can be moved to "Configuring Zowe > Configuring ZLux" Note that we have something very similar under Configuring for CLI - https://zowe.github.io/docs-site/user-guide/cli-configuringcli.html#setting-log-levels

When a user clicks the "edit on Github" button from the documentation site and makes changes to the doc, they should have access to our style guide. The work will include:

• Convert our style guide to markdown and adapt for a CONTRIBUTING.md file in the root of the repo.
• Create a pull request template that includes links to our contribution guidelines and requests for the basic info that any committer should provide about their proposed updates.

Useful resources:

• https://help.github.com/articles/setting-guidelines-for-repository-contributors/
• https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/

With the current setup, it is awkward to access a new topic. For example let's say you are here: https://zowe.github.io/docs-site/user-guide/api-mediation-api-catalog.html and then you want to go to the Zowe Overview section. You have to click on "Zowe Overview" then click again on the child "Zowe Overview" to get the content to appear.

I would prefer that each click take you to a new parent page, without the title>child with same title organization. Thoughts?

Investigate feasibility of moving to Netlify or possibly Zeit for automatic deployment.

The cost will be free, but it will require us to move to a new Domain name. I would like to move to one that we own/ control. www.zowedocs.com is available right now for purchase along with many other candidates.

The command

INSERT STC.ZOWESVR LOGONID(ZIUSVR) GROUP(IZUADMIN) STCID(ZOWESVR)

should have IZUSVR instead of ZIUSVR.

This is in file install-zos.md, to which I don't have write access.

As part of CII Badge requirement:

The project MUST provide, in each release, release notes that are a human-readable summary of major changes in that release to help users determine if they should upgrade and what the upgrade impact will be. The release notes MUST NOT be the raw output of a version control log (e.g., the "git log" command results are not release notes). Projects whose results are not intended for reuse in multiple locations (such as the software for a single website or service) AND employ continuous delivery MAY select "N/A". (URL required)

Ting UF Chen suggested checking for broken links in the build, and found this python tool. While I'd rather use something available in NPM for automatic builds, it's great as a desktop solution. In the short term we should be checking occasionally using that tool.

As far as the automatic build, I will probably use this tool and run it automatically in the deploy script. If it will stop the deploy from happening or just output broken links is yet to be determined.

The z/OSMF team are updating the z/OSMF configurations for Zowe. The documentation needs to be updated to integrate the new config doc. z/OSMF team expects to provide an early draft on Sep 14.
This is the topic to be updated: https://zowe.github.io/docs-site/user-guide/systemrequirements.html#z-osmf-requirements

Currently, the search only supports scanning headings. We need to provide an enhanced search experience by supporting searching keywords in the whole docs site.

Command-line based installations can be confusing for users who are new to CLI.

Document how to verify installations for node.js, npm, C++ compiler, python, etc... (see email from John L).

For example, "node --v" returns currently installed node version.

From @nkocsis on August 27, 2018 14:10

Update https://zowe.org/contribute/
to include instructions on how someone can open a Waffle Issue against Zowe

Copied from original issue: zowe/zac#10

There is discussion to rename these two terms. Created this issue to track the doc impact.

The troubleshooting section is inconsistent. We should improve consistency and address the following:

• The first heading is "Known issues", one of which is about MVD and one is about explorer server. Both are valid, but seem out of place at the top with no introductory sentence to say "these are issues you might encounter with X components. I think we should organize the issues by product.
• There is no intro sentence for "Troubleshooting installing the Zowe runtime" heading. What problem does the procedure solve? What is the goal of someone following the procedure? After performing the procedure, what is the result?
• "Troubleshooting installing zLux" section is more of a general checklist for troubleshooting rather than specific issues and solutions. Perhaps we should have a brief section separately named "Troubleshooting tips" or "General troubleshooting information" that has a bullet-list of items that users should review when troubleshooting each component. For CLI, this would be A. check the log files B. issue a zowe -v command to check the currently installed version, etc...
• "Troubleshooting installing explorer server" is also somewhat general checklist/procedure for troubleshooting.
• For any specific known issues/errors, we should follow the format in the "Troubleshooting installing CLI" section". Error/problem, valid systems, symptom, and solution.

Open to discussing alternative designs for this section

From @Tbr00ksy on August 24, 2018 18:42

Need to review different site flows and improve user navigation. Jay/BJ/Jessica?

Proposed changes to the arrows in green.

Copied from original issue: zowe/zac#6

User logs onto MVD with UID/PWD
The VT terminal app asks for "login as;" Is there a way the UID/PWD from MVD could be propogated through to the VT terminal ?

Comment history rom previous repository:

• do we know that the prompt for username & password is the same for all Z systems? If so, string matching will work.. if not, well, string matching is all we can do within the standard protocol (certificate-based login is great but yet to be solved in the web context!). It can be a best-effort auto-login perhaps that I can add a simple pattern match.. the terminal does support this ability.
  What is the security answer for the terminal getting the password? The username is shared via App framework so Apps can act upon it, but the password is not saved. I'd hate to introduce some backdoor to the effect of "all Apps declaring themselves as terminals get to see the password!" because there could be rogue Apps that disguise as a terminal simply to steal the password.

• Some terminals (such as putty) allow for the username to be automatically entered, but don't do so for password. That makes life slightly easier but still requires input.

• This is a security hole as someone who “walked” away from their terminal would be exposing services not already authenticated by them. As such, they could “blame” Zoe for allowing access to USS. Of course, they shouldn’t leave their screen unlocked but it is something we can predict will happen and shouldn’t contribute to a bad situation.

An alternative would be to have a “passphrase” where if someone opened a service that Zoe could authenticate to the passphrase could then access and provide the user/password combo like many services do (like 1Password). Even then, I’d rather have someone write a smart plugin than provide that as a base capability. I think it has more downside for negative reviews from a security perspective than upside in saving a few keystrokes.

Matt Hogstrom
[email protected]
+1-919-656-0564
PGP Key: 0x90ECB270
Facebook https://facebook.com/matt.hogstrom LinkedIn https://linkedin.com/in/mhogstrom Twitter https://twitter.com/hogstrom

“You can’t put too much water in a nuclear reactor"

On May 23, 2018, at 13:16, Sean Grady [email protected] wrote:

Some terminals (such as putty) allow for the username to be automatically entered, but don't do so for password. That makes life slightly easier but still requires input.

• Ultimately if you're using the standard username+password prompt of a unixoid terminal, that password needs to be kept somewhere. I am a proponent of passwords either being in your head or encrypted on your machine, rather than in the cloud or in a browser with untrusted javascript. So, even passphrase solutions are concerning to me, and I think the best we can get while maintaining security is auto-typing username but leaving password up to the user, or choosing a different authentication method.

However, the "easy" way of auto-login via keys instead of passwords leads to an interesting question of where do keys get stored in this web-based system, and suddenly I think it brings you right back to a passphrase-like solution.

• Currently no doc updates for this item per Sean..

• A lot of apps challenge the user once and once they have authorized to the app (such as our Eclipse desktop solutions) then use that UID and password to allow the user to connect to different hosts from the same front end. This feels good to me and what SSO should do. Once a user has logged onto MVD I don't think they should be re-challenged to use any of the apps within it. If we are worried about users leaving their desktop and someone then activating an app, the solution is screen saver lockouts, ...
  Also with one time use passwords such as through MFA once that has been used for MVD logon every app within should then be authorized through that initial trust.
  We should talk more about SSO at the face to face, but I'd like a lifecycle so that every app gets a chance to lifecycle when MVD is logged on, logged off. The VT terminal would then be one of these.

The "Install Plugin to CLI" doc topic has useful information but is difficult to follow. How to install a plug-in is already covered in each plug-in doc, but how to update/uninstall is burred in complexity within this topic. Make it simple for the user to learn about updating/uninstalling Zowe CLI. Add the following articles and remove Install Plug-ins:

• Update a plug-in
• Uninstall a plug-in

We currently have 3 major sections - User Guide, Developer Tutorials, and Samples.

A few issues and ideas to start a conversation:

• Some content currently in user guide is meant for Zowe developers (those who want to develop plugins/apps for Zlux, for example). This content is in the Extending zLux section. It ilooks like SDK doc - doc that describes how to use the features of a framework to develop plugins. I think we should keep the User Guide focused on usage, not development. However, INSTALLING plug-ins applies to users, and that's what should be documented in the Extending sections.
• Related to the above bullet - we have Imperative CLI Framework doc for developers in the /imperative GitHub Wiki. It is not a tutorial, but could belong in a Developer Guide along with the Zlux developer material.
• We have content in dev tutorials for onboarding an api to mediation layer. This is content meant for developers, but it isn't an optional tutorial - it is really the core documentation for how to accomplish something. Does this make sense to have here? I've also heard suggestions that perhaps there needs to be a separate Admin Guide to describe this type of content. Need to discuss with Andrew J.

In conclusion, perhaps we need a SDK/developer focused area to add the zLux framework and Imperative (the cli framework) doc. We should consider use cases/personas to understand what major sections we should have on the site (Admin Guide?). We should keep the user guide focused on install/config/usage. If we have an admin guide, some of that install/config info would fit there instead.

Open to ideas/discussion.

Explore options for embedded help to enable customers who have limited internet network to access doc. Need to investigate the possibilities and efforts of each option and make decision.

The following options are under investigation:

• F1 help in MVD
• Package doc as a plug-in and integrated into MVD
• Help displayed in search bar in MVD

Some thoughts from Sean:

Sometimes browsers have PDF viewers, but other times they don’t… PDF is a format that can be used to spread viruses so companies may disable PDF-in-browser support. So, I am thinking PDF is not the format to use for presenting in MVD.
Probably, MD would make sense as an alternative.

But, either way, we do not yet have an App meant for this, so we need to think about what requirements it would have, such as:

F1 help I think would re-use the same App, you’d just have different files for different topics.
The search bar doesn’t exist yet, but the idea for it is that Apps can be capable of responding to search requests, such that the result they give can be opened within that App.
So, again we’d re-use this hypothetical App such that when you search, it can pick out results that when clicked in the search UI, would open that App with that document.

@adambattenburg ,
I found a broken link at https://zowe.github.io/docs-site/samples/react-sample.html

Could you please take a look and help to fix that? Thanks!

This issue is to track the doc work for zTrail onboarding. This is in backlog now so stay tuned when it starts.

Resources:
https://pages.github.ibm.com/zTrial/z-cloud-trial/onboard/prelim/

Per @nannanli's discussion on slack, we need a way for users to select different versions of the doc site based on what version of Zowe is installed.

Further considerations will be if we change tutorials, or just the user guide for each version.

Some graphics in the automatically generated PDF file exceeds the border of the page. Please take a look fix this problem. See https://ibm.ent.box.com/file/310780645276.

An issue from Slack: https://ibm-systems-z.slack.com/archives/CA2PBRTEH/p1535074249000100

NPM audit reports this warning:

We found a potential security vulnerability in a repository for which you have been granted security alert access.
 
Known high severity security vulnerability detected in string <= 3.3.3 defined in package-lock.json.

We may need to switch to another broken link checking tool. For example:

• https://validator.w3.org/checklink or https://github.com/w3c/link-checker
• https://wummel.github.io/linkchecker/

For any of the choice, we need to serve our static HTMLs as website and let the tool to test. Also the installation is much more complicated and need to properly documented.

The section for "Install CLI from Package" and the section for "Install CLI from Bintray" in cli-installcli.md are slightly inconsistent.

Both should have very similar steps, with the exception of the registry set step and some of the syntax.

For example, install from Bintray should also include the "Address Prereqs" as step 1.

Create scenarios/usage topics for Zowe CLI and other components, if applicable.

This is a comment from the Slack channel. Besides adding link to the PDF file on the zowe.org website, we can consider add install/config PDF download as a section on the docs site home page so users can more easily locate it instead of hunting around.

Current path to find the PDF file:
zowe.org -> zowe.org/download/ (read documentation button) -> https://zowe.github.io/docs-site/user-guide/installandconfig.html -> “About this documentation” link -> Downloadable PDF file

Expected:

1. zowe.org -> zowe.org/download/ (read documentation button + download user guide in PDF link)
2. zowe.org -> zowe.org/download/ (read documentation button) ->https://zowe.github.io/docs-site Home Page (Download PDF button)

From @Tbr00ksy on August 24, 2018 18:37

The contribute page (https://zowe.org/contribute/) could be revamped in several ways:

• Add links and descriptions on the slack channels
• Add graphic for squads and brief description of how the interact?
• Add link to squad Waffle boards/backlog
• Add link to groups.io for list of list of scheduled squad meetings

Copied from original issue: zowe/zac#5

@jackjia-ibm we have an error in Jenkins stating "ENOENT: no such file or directory, stat '/home/jenkins/.cache/yarn/v2/npm-lodash-4.17.11-b39ea6229ef607ecd89e2c8df12536891cac9b8d/fp/flattenDeep.js'"

The PR passed all checks before being merged, but then failed after being committed to Master. This might be something we need to keep and eye on in the future.

Automate doc publishing process to improve efficiency.

• Automate deploying to website when code is checked-in to master branch. This is tracked in #39
• Include PDF build in the automation @chentingcathy
• Find alternative PDF builder as opposed to ditamap method @PlutoZhang
• Broken link check. Need to explore tools to run accessibility test against doc. This is now tracked in issue #54
• Style check. Need to integrate Acrolinx (or similar tool) into doc build to enable automatic check.

Some code blocks/examples don't display at all in the published website. I believe this happens when the code wrapped in is indented one Tab too far in the markdown. Here is one example, but I know that there are others. Seems like a high priority to fix:

https://zowe.github.io/docs-site/user-guide/planinstall.html#planning-for-installation

Allow the ability to override the PROCLIB where ZOESVR is placed. zoe-install.yaml should have a proclib variable, default to CALCULATE, with values such as SYS1.PROCLIB, USER.PROCLIB, and so forth so that an installer can exercise manual control.

@John-A-Davies @JoeWinchester should both review this Issue and determine if it can be removed from docs-site repo. Doesn't seem to be doc-focused.

When trying to login with any user on Explorer, zLux or any other interface, logon is rejected with the following message:

CWWKS9104A: Authorization failed for user aaaaaa:z/OSMF AuthorizedUser Credentials while invoking Atlas on /api/zos/username. The user is not granted access to any of the required role : ÝizuUsers

By the way, the user is part of IZUUSERS group.

We don't seem to have instructions for how to un-PAX the installation media on a PC. We only document how to FTP to mainframe and expand the PAX there.

If a user wants to open the PAX to install Zowe CLI with the .tgz bundle, instructions for how to open on PC will be helpful.

I received feedback from a community member - "I had to extract it using 7zip and then unzip the zowe-cli-bundle that was zipped inside the pax"

When opening a PDF, we can direct the user to the relevant section using a link like https://zowe.github.io/docs-site/Zowe_User_Guide.pdf#page=5. It is also be possible to go to a section like "https://zowe.github.io/docs-site/Zowe_User_Guide.pdf#contents". However I haven't been able to manage this yet not understanding how the PDF is generated. I think I just have the wrong section names.

While we could go to page numbers, I'd like to avoid that and instead navigate to sections that are the same as the file name or Title. This might require making sure we have no duplicates in title names, but also might be less brittle in the long run.

This could then be placed in the page header along with 'Last Updated' and 'Edit Page'. Let me know what you think and maybe @nannanli you could investigate if we can link to specific sections of the doc instead of page numbers?

Currently verifying the PAX file is a mandatory step and the procedure is documented only in the zowe.org right after users click "Agree" on the license page: https://projectgiza.org/Downloads/verify.html

Some users might assume that after saving the file, all is done on the download site. Then they go directly to read documentation without noticing that a verification step is required on the download site. Therefore it makes sense to document the procedure in docs site User Guide: https://zowe.github.io/docs-site/user-guide/gettingstarted.html

Within this topic, further divide it into:

• Verifying the file (provide the current steps as well as link to download gpg)
• Transfer the file to z/OS

Comments from Mike:
we should a) make it very obvious how to get from ‘download’ to ‘install docs’ (at the time when I did this, I had to hunt a little to find the docs) and b) the first step in the install docs should be to verify the download. We should state it as a step and I imagine some people will skip it - but that needs to be their choice not an accident.