Update the doc site URL

[nannanli]

Update the doc site URL from https://github.com/zowe/docs-site/ to https://github.com/zowe/docs/.

After the change is made,

• need to run link checker and fix broken links.
• need to investigate if we can set up redirection from old URL to new URL. Some social posts used the old URL.
• need Cathy (Chen Ting) to update the sitemap for SEO.

[nannanli]

Broken links that will arise with this change:

C:\GitFolder\docs-site\docs.vuepress\config.js (2 hits) Line 3: base: '/docs-site/', Line 8: repo: 'https://github.com/zowe/docs-site', C:\GitFolder\docs-site\docs\contribute\CONTRIBUTING.md (5 hits) Line 5: We provide you a set of guidelines for contributing to Zowe documentation, which are hosted in the [Zowe / docs-site][b5d824b5] on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose content changes to this documentation. Line 7: [b5d824b5]: https://github.com/zowe/docs-site "https://github.com/zowe/docs-site" Line 7: [b5d824b5]: https://github.com/zowe/docs-site "https://github.com/zowe/docs-site" Line 66: [8c024bb7]: https://zowe.github.io/docs-site/user-guide/aboutthisdoc.html#sending-a-github-pull-request "https://zowe.github.io/docs-site/user-guide/aboutthisdoc.html#sending-a-github-pull-request" Line 66: [8c024bb7]: https://zowe.github.io/docs-site/user-guide/aboutthisdoc.html#sending-a-github-pull-request "https://zowe.github.io/docs-site/user-guide/aboutthisdoc.html#sending-a-github-pull-request" C:\GitFolder\docs-site\docs\extend\tutorials\ReactJSUI.md (2 hits) Line 7: Take a look at the Creating a RestAPI with Swagger documentation using Liberty tutorial for the background to the Restful API with Swagger documentation we will be using. Line 48: Next lets look at calling our API created in the creating a RestAPI with Swagger documentation using Liberty tutorial. Following Redux structure, this call will be in our action.js file. We won't be looking at the entire file, but instead the relevant fetch request. C:\GitFolder\docs-site\docs\user-guide\download-pdf.md (1 hit) Line 3: You can download this documentation for Zowe as PDF file. Click here to view and download the PDF file.

[jackjia-ibm]

A new branch issue-145 is created to track the changes.

A new repository https://github.com/zowe/docs-site-temp is created for redirecting the https://zowe.github.io/docs-site to https://zowe.github.io/docs.

We need to schedule a time to work on the pending updates together:

• Create a PR for branch "issue-145" and merge to master.
• Rename the "docs-site" repository to "docs".
• Rename the "docs-site-temp" repository to "docs-site".
• Update Jenkins to use the new repository "docs":
  • Jenkins of building gh-pages,
  • Jenkins of building PDF file.
• Update https://zowe.org to link to new URL https://zowe.github.io/docs. Here are links we should check:
  • https://zowe.org/home/ menu bar on top and links on very bottom,
  • https://zowe.org/home/ "What's New" link in "Announcements" section,
  • https://zowe.org/home/ Documentation section at the bottom,
  • https://zowe.org/download/ documentation links,
  • https://zowe.org/faq/ Resources section at the bottom,
  • https://zowe.org/contribute/ Onboarding GitHub URL,
  • https://projectgiza.org/Downloads/post_download.???.html Documentation links.
  • Verify Google Analytics tracking code.
• Update hooks to waffle.io.
• Create pull request on Algolia search configurations at https://github.com/algolia/docsearch-configs/blob/master/configs/zowe.json.
• Notify teams to modify other pages, like repository READMEs of zowe-cli, db2 plugin, cics plugin, vsc plugin, sample plugin, etc.
• Do we have other websites, or maybe mailing list information which link to https://zowe.github.io/docs-site, or rely on https://github.com/zowe/docs-site repository?

[BrandonJenkins14]

Regarding @jackjia-ibm last bullet, we do have some incoming links to the doc site to fix as part of this issue. Primarily in some internal CA documentation and in the CLI github repository readmes. (zowe-cli, db2 plugin, cics plugin, vsc plugin, sample plugin).

[nannanli]

Per Adam, we also need to update the Google Analytics account to use the new URL. I think the account owner is Matt. Will check.

[jackjia-ibm]

Thanks @BrandonJenkins14 a lot for the input, I wasn't aware of those READMEs.

And thanks to @nannanli and Adam, yes we do have GA tracking code needs to be adjusted accordingly. I have GA account and tracking code access, will work on that. I've updated the above list to reflect the missing points.

[BrandonJenkins14]

Is this issue still relevant @nannanli @jackjia-ibm ?

[jackjia-ibm]

I worried we may have missed the timeframe to swap. We may have advertised too many urls with docs-site on various channels, so this task became over too complicated. What do you think @nannanli?

[nannanli]

@jackjia-ibm Agree. If we switch to new URLs, old URLs in blogs and people's bookmarks, etc will be inaccessible. I'm wondering if there is a possibility to proceed with this now by setting up redirects. I mean:

• We update the URL to use /docs.
• When people use old URLs /docs-site to access the site, they will be redirected from docs-site to docs directly without even noticing that the URL has changed. When they visit https://zowe.github.io/**docs-site**/latest/getting-started/summaryofchanges.html, they will be directed to https://zowe.github.io/**docs**/latest/getting-started/summaryofchanges.html

How much effort would it take if possible? However, this is not a critical user experience issue.

[jackjia-ibm]

@nannanli Yes we will have a "redirect" in place, just it's not ideal. By using GitHub Pages, we have 2 ways to "redirect":

1. With the new docs-site repo (renamed from docs-site-temp) redirect all missing pages to docs repo. This actually means all links are missing, with HTTP 404 error, then falls back on 404.html error page, in that page, we tell the browser to redirect the user to https://zowe.github.io/docs/ or https://zowe.github.io/docs/latest/getting-started/summaryofchanges.html, https://zowe.github.io/**docs-site**/latest/getting-started/summaryofchanges.html. This is similar to the 404 handling we run on redirecting https://zowe.github.io/docs-site/getting-started/summaryofchanges.html to https://zowe.github.io/docs-site/latest/getting-started/summaryofchanges.html when we having the archived version.
2. On the new docs-site repo (renamed from docs-site-temp), we create 1-to-1 match of html pages as original, but with empty content and meta http refresh html header. So when accessing https://zowe.github.io/docs-site/latest/getting-started/summaryofchanges.html, we got an empty page with HTTP 200 success, and then when the browser parse the html content, it will know we need to redirect to https://zowe.github.io/docs/latest/getting-started/summaryofchanges.html.

So both ways look not too bad for end-user using browser, they may not notice much obvious trouble. But for robots, like search engine bot, they may be confused with the http status code. Ideally status code for redirection is 301. With the 1st option, the http status code is 404, means page doesn't exist. With the 2nd option, the http status code is 200, means nothing wrong. The bot may not know we need a redirection if it doesn't parse/run the html or javascript code on the page. That's why both ways are considered bad practices in the web development world.

If we are ok with this, we can perform change. At least to end-user, the redirection is not too bad.

In addition, we need to update Algolia search config (https://github.com/algolia/docsearch-configs/blob/master/configs/zowe.json#L5) to index on the new urls.

[nannanli]

This issue is now part of issue #650. Instead of changing to https://github.com/zowe/docs/, the new URL will be docs.zowe.org and the DNS will handle the redirect. All locations that might be hit are moved to #650. Closing this one.