Migrating docs from source to docs repo #6899
Conversation
|
With removing the files we'll have many broken links internally and externally. Can we replace each removed file with a placeholder file with a description and link to new file? |
|
@iSazonov We should not be linking to docs on GitHub. We should only be linking to published docs on docs.microsoft.com. Can you provide some examples to help me understand the impact? Also, I added a DOCSMIGRATION.md file with that information, it that not sufficient? |
|
@sdwheeler I meant that issues in the repo contain links on the docs. Also somebody can have links in blog posts. |
|
@iSazonov That is another reason to not have docs like that in the source repo. In docs.microsoft.com we have a way to redirect those external links when they change. We cannot do that when the link points to GitHub. |
|
@sdwheeler Please see the comment #6002 (comment) |
|
@iSazonov, @joeyaiello and I discussed this and in general linking directly to GitHub repo is not recommended. Linking directly to a commit guarantees that link will work, but won't get the latest revision. This is one of the reasons to move the docs not repo specific out so that deep links should continue to work. |
|
@SteveL-MSFT I assume that most of these references to documentation do not use commits. People will do this in the future too and GitHub does not block it. Actually the problem is not this. People will get the Page not found, and we can show them a page with a link to the new document location. I suppose it will be more user friendly. I don't insist if you don't see the problem. |
|
@iSazonov seems like maybe we can use this to redirect https://help.github.com/articles/redirects-on-github-pages/ ? |
|
@SteveL-MSFT @iSazonov that redirection only applies to GitHub Pages published using Jekyll. |
|
@sdwheeler too bad. For now, I would suggest moving ahead as-is. @iSazonov you have a valid concern and we should be more aware of that going forward if we add new docs to this repo. If there is sufficient community feedback, we can consider putting replacement .md files that tell the user where the new documentation is. |
|
LGTM. |
|
Not even the links of the main readme were updated to point to the docs site, this is not really a good migration process |
|
@sdwheeler can you submit a PR to update the links on the README.md? |
|
@SteveL-MSFT Will do. I had a previous PR for this but it got closed. Will work on a new one. |
|
@sdwheeler see pr #6981 and feel free to modify it to your liking |
|
Folks, people rely on these installation instructions. I have internal documentation that points to these links so folks know how to install PS Core. It is way not cool to have these install links broken for multiple days. :-( |
PR Summary
The docs folder in this repo contains a lot of documentation about the PowerShell source code and build environment.
It also has contained documentation about about installing and using Powershell.
That documentation really belongs in the PowerShell/PowerShell-Docs repo.
We are in the process of migrating the user-focused article to the docs repo.
This file records which files have been migrated.
2018-05-18
The following files have been moved to the PowerShell/PowerShell-Docs repo.
PR Checklist
.h,.cpp,.cs,.ps1and.psm1files have the correct copyright headerWIP:to the beginning of the title and remove the prefix when the PR is ready.[feature]if the change is significant or affects feature tests