This guidance is for SMEs who are listed as the author of an Azure technical article that needs to be retired, renamed, or moved in docs.microsoft.com/azure.
If you're a member of our Azure community and you think an article should be retired for any reason, please leave a comment in the comment stream for the article to let the author know something is wrong with the article.
When authors want to retire, rename, or move articles, they need to follow specific steps to avoid bad experiences on the web site. Our goal should be to gracefully retire content so users of the website don't find broken links and receive 404 errors.
If you are retiring an article, the first thing you should do is republish the article as no-index/no-follow a few weeks before you actually delete it. This is considered the best practice "pre-work" for retiring content. Doing this removes the article from search engine indexes so people won't find the article in search. To do this, add the following line as the last entry in the metadata section of the article:
ROBOTS: NOINDEX, NOFOLLOW
Note: This is the first step if you are retiring an article. If you are renaming or moving the article, you can do this as the last step.
Step 2: Turn the original article into a redirect, and create the new file if you are renaming or moving a file.
In our publishing workflow, the article you want to retire, rename, or move must remain in place so you can create a redirect to the new article or to the replacement content. You turn an article into a redirect by replacing the article metadata with redirect information. Make the changes that match what you want to do:
-
Retire: Update the metadata so the article redirects to the service landing page. If the service is being deprecated, redirect the pages to the Azure hub page on docs.
-
Rename: Create a copy of the article, give the file its new name, and then update the metadata of the original article so the article redirects to the new one.
-
Move: Create a copy of the article in the new location, and then update the metadata of the original article so the article redirects to the new one.
See the OPS documentation for instructions on how to turn an article into a redirect.
Do not delete articles from the azure-docs-pr or azure-docs repositories, period. If you delete an article, you cannot create the article-level redirects, which guarantees that customers will experience 404s.
Do not rely on redirects to take care of crosslinks from other articles. Update or remove the cross references to the article you are retiring, renaming, or moving, including links in articles owned by other authors.
-
Ensure you are working in an up-to-date local branch – run
git pull upstream master(or the appropriate variation on this command). -
Scan the azure-docs-pr/articles folder and the azure-docs-pr/includes folder for any articles and includes that link to the article you want to retire, move, or rename. Either remove the crosslinks or replace them with an appropriate new crosslink. You can use a search and replace utility to find the crosslinks if you have one installed. If you don't, you can use Windows PowerShell for free! Here's how to use PowerShell to find the crosslinks:
a. Start Windows PowerShell.
b. At the PowerShell prompt, change into the azure-docs-pr\articles folder:
cd azure-docs-pr\articlesc. Type this command, which will list all files that contain a reference to the article you are deleting:
Get-ChildItem -Recurse -Include *.md* | Select-String "<the name of the topic you are deleting>" | group path | select nameIf you prefer to send the list of file names to a text file (in this case, named psoutput.txt), you can:
Get-ChildItem -Recurse -Include *.md* | Select-String "<the name of the topic you are deleting>" | group path | select name | Out-File C:\Users\<your account>\psoutput.txt -
Add and commit all your changes, push them to your fork, and create a pull request to move your changes from your fork to the master branch of the main repository.
If your article existed on ACOM, you need to request that the ACOM-to-DOCs redirect file be updated so the old ACOM URL (azure.microsoft.com/documentation/articles/article-name) redirects to the new article on docs or to the service landing page. File a bug at https://aka.ms/acomtodocsredirect.
Publish your changes to the article repository by submitting a pull request. Ensure that the ACOM-to-DOCS redirection goes live the same day.
These cleanup tasks need to be performed immediately after the changes are published.
File a work item with the ACOM team to remove any crosslinks to retired articles from pages on azure.microsoft.com. If you renamed or moved articles, file a work item to have crosslinks on ACOM updated.
Check the FWLink tool for any FWLinks that might point to the article. Update the FWLinks to point at the appropriate replacement content; if you are not on the alias that owns the link, join it. If the owners won't update the link or let you join the alias, file a ticket at https://msdnhelp to have the link changed.
Determine if there are any high-traffic non-Microsoft inbound links to your content. Frequently, blogs, forums, and other web content point to articles. You can work with content owners to change or remove these links, and you can remove or update links from forum posts. Web analytics tools can tell you if there are any high-traffic inbound links you might need to manage in this way.
Do this ONLY if the content needs to be removed from search quickly due to legal or severe customer issues. Per best practices from Google, normal priority content should be removed from search through natural search engine processes. Go to these web pages to remove cached web pages from search engines:
The length of time an article-level redirect stays in place is TBD.