diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..143518334a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,64 @@ +# Contributing to Windows Server technical documentation + +Thank you for your interest in the Windows Server technical documentation! We appreciate your feedback, edits, and additions to our docs. +This page covers the basic steps for editing our technical documentation. + +## Sign a CLA + +All contributors who are ***not*** a Microsoft employee must [sign a Microsoft Contribution Licensing Agreement (CLA)](https://cla.microsoft.com/) before editing any Microsoft repositories. +If you've already edited within Microsoft repositories in the past, congratulations! +You've already completed this step. + +## Editing topics + +We've tried to make editing an existing, public file as simple as possible. + +### To edit a topic + +1. Go to the page on https://docs.microsoft.com/windows-server that you want to update, and then click **Edit**. + + ![GitHub Web, showing the Edit link](media/contribute-link.png) + +2. Sign in to (or sign up for) a GitHub account. + + You must have a GitHub account to get to the page that lets you edit a topic. + +3. Click the **Pencil** icon (in the red box) to edit the content. + + ![GitHub Web, showing the Pencil icon in the red box](media/pencil-icon.png) + +4. Using Markdown language, make your changes to the topic. For info about how to edit content using Markdown, see: + + - **If you're linked to the Microsoft organization in GitHub:** [Windows Server Contributor's Guide](https://github.com/MicrosoftDocs/windowsserverdocs-pr/tree/master/Contributor-guide) + + - **If you're external to Microsoft:** [Mastering Markdown](https://guides.github.com/features/mastering-markdown/) + +5. Make your suggested change, and then click **Preview Changes** to make sure it looks correct. + + ![GitHub Web, showing the Preview Changes tab](media/preview-changes.png) + +6. When you’re done editing the topic, scroll to the bottom of the page, and then click **Propose file change** to create a fork in your personal GitHub account. + + ![GitHub Web, showing the Propose file change button](media/propose-file-change.png) + + The **Comparing changes** screen appears to see what the changes are between your fork and the original content. + +7. On the **Comparing changes** screen, you’ll see if there are any problems with the file you’re checking in. + + If there are no problems, you’ll see the message, **Able to merge**. + + ![GitHub Web, showing the Comparing changes screen](media/compare-changes.png) + +8. Click **Create pull request**. + +9. Enter a title and description to give the approver the appropriate context about what’s in the request. + +10. Scroll to the bottom of the page, making sure that only your changed files are in this pull request. Otherwise, you could overwrite changes from other people. + +11. Click **Create pull request** again to actually submit the pull request. + + The pull request is sent to the writer of the topic and your edits are reviewed. If your request is accepted, your updates are published. + +## Resources + +- You can use your favorite text editor to edit Markdown. We recommend [Visual Studio Code](https://code.visualstudio.com/), a free lightweight open source editor from Microsoft. \ No newline at end of file diff --git a/Contributor-guide/Contributor-index.md b/Contributor-guide/Contributor-index.md deleted file mode 100644 index 7ca9a15a5b..0000000000 --- a/Contributor-guide/Contributor-index.md +++ /dev/null @@ -1,47 +0,0 @@ - - - - -# Windows Server technical content contributors' guide index - -> [!Note] -> Where possible, guidance for Windows Server content follows Azure documentation guidance. Some of the links below lead to Azure content because the guidance is the same. - -## General guidance - -- [Contribute to Windows Server documentation](git-steps-create-update-content.md) - -- [Content channel guidance](https://github.com/Azure/azure-content/blob/master/contributor-guide/content-channel-guidance.md) - -- [Style and voice](https://github.com/Azure/azure-content/blob/master/contributor-guide/style-and-voice.md) - -## Authoring articles: tools, processes, guidance - -- [Tools and setup for authoring in GitHub](tools-and-setup.md) - -- [Git commands to create or update an article](git-steps-create-update-content.md) - -- [File names and locations](file-names-and-locations.md) - -- [Metadata, product versioning, and trademarks](metadata-OSversioning-and-trademarks.md) - -- [Quality criteria for pull request review](contributor-guide-pr-criteria.md) - -- [Linking guidelines](create-links-markdown.md/) - -- [Rename or retire an article](rename-or-retire.md) - -- [How to undo almost anything with Git (GitHub blog)](https://github.com/blog/2019-how-to-undo-almost-anything-with-git) - -## Authoring articles: markdown - -- [Markdown syntax, OPS-supported Markdown extensions and HTML](https://opsdocs.azurewebsites.net/en-us/opsdocs/partnerdocs/gfm) - - [Printable markdown cheatsheet](./media/documents/markdown-cheatsheet.pdf?raw=true) - - [Create tables in markdown](https://github.com/Azure/azure-content/blob/master/contributor-guide/create-tables-markdown.md) - - [Create images in markdown](create-images-markdown.md) - -- [Metadata for Windows Server technical articles](https://ppe.msdn.microsoft.com/en-us/ce-csi-docs/ops/ops-onboarding/managing-content/content-meta-data?branch=master) - -## Community management - -All topics in Docs.microsoft.com include a LiveFyre comment control at the bottom of the page, as well as inline. To respond to comments, you must first [Sign up for LiveFyre](https://github.com/Microsoft/azure-docs/blob/79cc9a099211fddb43ab739136df95bfeaf4c5cd/contributor-guide/tools-and-setup.md#sign-up-for-livefyre). diff --git a/Contributor-guide/Tips-gotchas.md b/Contributor-guide/Tips-gotchas.md deleted file mode 100644 index d58af00a5f..0000000000 --- a/Contributor-guide/Tips-gotchas.md +++ /dev/null @@ -1,41 +0,0 @@ -# Tips and gotcha's - -If you're new to Git, learning to work effectively can be frustrating. Info is collected here so it's easier to find than if it's included within the other info in this guide. - -## Basics: - -Commands in this Contributor's Guide assume you've configured Github to specify the default repo where you pull files from. In Github terminology, where you pull files from is your *upstream*. Where you push files to is your *origin*. - -Because of on how our repo and workflow are designed, your upstream should be set to our repo, which is under the Microsoft organization - https://github.com/Microsoft/WindowsServerDocs-pr and your origin should be your fork of this repo, which is under your own Github account. For example, https://github.com/MY-GITHUB-ALIAS/WindowsServerDocs-pr - ->To check your settings, type ```git config -l```. Look at the URLs to make sure they refer to location you intended. - -Some basic branch tips: - -- Work in branches, not in your local copy of Master. This makes it easier to recover from problems in your branches and go back to a good, known point. - -- Base your local branches on a branch in the shared repo, not on your remote fork. Then, you'll push your local branches to your remote fork. From your remote fork, you'll request to have the updates in your fork merged into the shared repo. The commands in this article show you how to do this. - -- When you create a local branch, your command tells Git what branch you want to base your new branch on. This is when and how you specify master, or a milestone or feature branch. For example, this command creates a new branch from an upstream branch and then checks out the new branch so you're ready to work in it: - - git checkout upstream/upstream-branch-name -b your-local-branch-name - -For markdown help, start with this [article](https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github/) in Github. For tables, see this [one](https://help.github.com/articles/organizing-information-with-tables/). - -## Gotcha's - -### Deleting files -It doesn't work to just delete a file from your file system. Use Git commands to let the system know you intended to do this, otherwise your deleted files will probably become zombie files that reappear. And never at a good time. After all, this is a source control system and if you don't tell it you really want to get rid of these files, it will helpfully add them back for you. Thanks, Git! For instructions, see [Rename or retire an article](rename-r-retire.md). - -### Merge conflicts - -If you get a merge conflict while working locally, you either need to fix it or back out of it. The vast majority of the time it's best to just fix them, unless they're not your files. Keep in mind if you do nothing, you might be blocked from pushing your changes to your origin, so you will have to do to something. - -**How to fix** -- Azure guidance has more info about this and instructions for resolving the conflict. **A PR with merge conflicts should never be accepted**. Be sure to substitute the name of our repo and branches in all examples when you review the [instructions](https://microsoft.sharepoint.com/teams/azurecontentguidance/wiki/Pages/Resolve%20a%20local%20merge%20conflict%20yourself.aspx). - -**How to back out** -- If the conflicts are in files you don't own or there's a reason you can't fix them at the time, here's how to back out. This resets your local set of files back to how they were before the merge conflict happened. Run this command: - -```git merge --abort``` - -If you haven't staged and committed your local work, you can do so now. But, if you push those changes and open a PR, the conflict will probably reappear if it was in the files with changes. You'll have to fix it or get help from someone else to fix it, before the request can be accepted. Because of this, it's best to only use the method to unblock yourself if you have urgent work, such as a critical update. - diff --git a/Contributor-guide/common-git-bash-commands.md b/Contributor-guide/common-git-bash-commands.md new file mode 100644 index 0000000000..7116e68484 --- /dev/null +++ b/Contributor-guide/common-git-bash-commands.md @@ -0,0 +1,39 @@ +--- +title: Common Git Bash commands for use with GitHub +description: A list of somme of the most frequently used commands in Git Bash when working with GitHub. +author: eross-msft +ms.author: lizross +ms.date: 05/06/2019 +--- + +# Common Git Bash commands + +These are some of the most-used commands in Git Bash, based on when you will use them in your content creation and editing process. + +## Master branch-related + +You must always use master as your base for any new branch. + +| Command | Description | +|---------|-------------| +| `git checkout master` | Switch to master from any other branch | +| `git pull upstream master` | Update your local copy of master from the production repo | + +## Branch-related + +| Command | Description | +|---------|-------------| +| `git branch` | See your existing branches | +| `git checkout -B ` | Create a new branch | +| `git checkout ` | Change to another branch | +| `git status` | Check what’s going on in your branch | +| `git branch -D ` | Delete an existing branch (making sure you’re not in it) | + +## Check-in-related (done as a group, in order) + +| Command | Description | +|---------|-------------| +| `git add .` | After you save your work, add it to a branch | +| `git commit -m “public comment, including quotes”` | Commit your changes to your branch | +| `git pull upstream master` | Update your local copy of master from the production repo | +| `git push origin ` | Push to the remote version of your local branch | \ No newline at end of file diff --git a/Contributor-guide/contributor-guide-official-windows-terms.md b/Contributor-guide/contributor-guide-official-windows-terms.md deleted file mode 100644 index a9f7102356..0000000000 --- a/Contributor-guide/contributor-guide-official-windows-terms.md +++ /dev/null @@ -1,9 +0,0 @@ -Use the official names for references to versions of Windows Server and installation options. - -Versions are: - -Installation options are: - -Source: - -Resources \ No newline at end of file diff --git a/Contributor-guide/contributor-guide-pr-criteria.md b/Contributor-guide/contributor-guide-pr-criteria.md deleted file mode 100644 index 4d811a2313..0000000000 --- a/Contributor-guide/contributor-guide-pr-criteria.md +++ /dev/null @@ -1,43 +0,0 @@ -# Quality criteria for pull request review - -Pull requests must meet minimum criteria to be accepted for integration into the repo. Pull request reviewers generally review only what is new or changed, using the blocking and non-blocking quality review items listed in this article to evaluate the changes. Reviewers may ask for more information or for a requestor to fix issues before accepting a pull request. The requestor is responsible for making the changes. - ->[!IMPORTANT] ->Opening a pull request triggers quality checks and publication to our internal staging site. It's your responsibility to review both, from links in comments \(on the Conversation tab of the PR, click **Show all checks** > **Details**\). After you've done this, indicate it by adding the **"ready-to-merge"** label to the PR. \(Click **Labels** or the gear to the right of the comment stream in the PR.) If you can't add the label \(come contributors have reported this), add 'ready-to-merge' a comment to the PR and send email to reviewer's alias, wssc-pra@microsoft.com. - -## Blocking content quality items - -The updates must comply with the following criteria to be merged. - -| Category | Quality review item | -|----------|---------------------| -|Prerequisites| The pull request has no:
- validation errors or warnings
- merge conflicts
- obvious content regressions
- embedded repo or any unusual, extraneous files| -|Repo integrity |Pull request contains fewer than 100 changed files unless it's updating a release branch from master or doing a similar bulk update like a metadata fix. (Really, a PR should contain far fewer than that, but after 100 changed files, GitHub doesn’t display the diffs).| -|Repo integrity| Pull request does not get merged by the person who created the pull request.| -|Naming |File names for new files follow the [file naming guidelines](file-names-and-locations.md).| -|Naming |New folders introduced into the repo follow the [folder naming guidelines](file-names-and-locations.md#folder-names-in-the-repo).| -|Naming/SEO|The H1 title has enough information to describe the content of the article, to differentiate it from other articles, and to map to likely customer keywords. For example, an H1 title of "Overview" doesn't meet this criteria.| -|Content|It's a technical document. See the [what goes where guidance](content-channel-guidance.md).| -|Content|It has an introductory paragraph, and a procedural or conceptual body of content. It has enough content to stand on its own as an article and isn't a small fragment of information.| -|Content| It follows standard formatting and content design: elements that should be numbered lists are numbered, elements that should be unordered lists are bulleted. This is basic usability.| -|Content| It has no unusual graphics, information architecture or structures, or obviously non-standard designs.| -|Site/design functionality| The article doesn't have a manually authored TOC within the contents. The article must rely on H2s for its on-page TOC.| -|Site/design functionality| If H2 headings are used, there are at least two. Any H3 heads are preceded by an H2 heading. Using one H2 heading creates a single-item article TOC. Use an H2 headings before an H3 heading to ensure a TOC is created.| -|Markdown| Article contains no blocks of HTML; minor inline HTML is permitted – such as superscript, subscript, special characters, and other minor formatting that Markdown doesn't support. HTML tables are allowed ONLY if the table contains bulleted or numbered lists, but that usually indicates the content could be simplified so it can be coded in Markdown.| -|Markdown |Custom markdown elements are used where appropriate. Ex: Notes are coded using the !NOTE extension, not as plain text.| -|Images|Images include alt text. **This is an accessibility requirement that must be fulfilled as part of release criteria.** [Guidelines here](https://worldready.cloudapp.net/Styleguide/Read?id=2665&topicid=28349). | -|Images |Animated GIFs are not accepted into the repo.| -|Images | Images have clear resolution, are free of misspelled words, and contain no private information [See the image guidance](https://github.com/Azure/azure-content/blob/master/contributor-guide/create-images-markdown.md). | -|Staging| The article has been previewed on staging and doesn't contain any obvious formatting issues:
- A numbered or bulleted list that appears as a paragraph
- Code in a code block appearing partly in the code block and partly outside it
- Numbered steps numbered incorrectly due to faulty indentation| - -## Non-blocking content quality items - -For these items, pull request reviewers provide feedback and instructions for the author to follow up with fixes in a later pull request. However, this feedback doesn't block the decision to merge. Authors should follow up within 3 business days with fixes. - -| Category | Quality review item | -|----------|---------------------| -|Content|Articles should have a “Next steps” at the end with 1-3 relevant and compelling next steps. Brief text should be included that helps the customer understand why the next steps are relevant. (New articles only). -|Images|Images use the correct callout style and color, and screenshots use the correct border and placeholder style. [See the image guidance](https://github.com/Azure/azure-content/blob/master/contributor-guide/create-images-markdown.md).| -|Site/design functionality|The H2 headings, when rendered in the on-page TOC, should ideally wrap to no more than 2 lines. Longer headings make the article TOC harder to scan.| -|Style conventions|All titles and headings are sentence case.| -|Process|When you delete or rename an article, make sure you follow the process. Pull request reviewers should add the following comment and link in a comment:

*Please verify you followed the process in the contributor's guide: [Change the name of an article or delete it](rename-or-retire.md).*| diff --git a/Contributor-guide/create-new-using-github.md b/Contributor-guide/create-new-using-github.md new file mode 100644 index 0000000000..12082f4ebd --- /dev/null +++ b/Contributor-guide/create-new-using-github.md @@ -0,0 +1,212 @@ +--- +title: Create new Windows Server articles using GitHub and Visual Studio Code +description: How to create new Windows Server-related articles, using GitHub and Visual Studio Code, as a Microsoft employee. +author: eross-msft +ms.author: lizross +ms.date: 05/02/2019 +--- + +# Create new Windows Server articles using GitHub and Visual Studio Code + +As a Microsoft employee, you can follow these instructions to create and set up your GitHub account and tools, fork and clone the windowsserverdocs-pr repo, set up your remote branch, create a new article, and create a new pull request for approval and publishing. + +## Prerequisites + +Before you can start working in the repo, you must create and set up your GitHub account, set up two-factor verification, and install and configure all the necessary tools. If you’ve already done this, you can skip down to the [Fork the repository section](#fork-the-repository) of this article. + +1. [Create a GitHub account and profile](https://review.docs.microsoft.com/help/contribute/contribute-get-started-setup-github?branch=master#create-a-github-account-and-set-up-your-profile) + +2. [Link your account to your Microsoft account and to the Microsoft and MicrosoftDocs organizations](https://review.docs.microsoft.com/help/contribute/contribute-get-started-setup-github?branch=master#link-your-github-and-microsoft-accounts) + +3. [Turn on two-factor verification](https://review.docs.microsoft.com/help/contribute/contribute-get-started-setup-github?branch=master#enable-two-factor-authentication-and-create-an-access-token) + +4. [Authorize the build system to access your GitHub account](https://review.docs.microsoft.com/help/contribute/contribute-get-started-setup-github?branch=master#authorize-the-ops-build-system-to-access-your-github-account) + +5. [Install Visual Studio Code](https://review.docs.microsoft.com/help/contribute/contribute-get-started-setup-tools?branch=master#install-visual-studio-code) + +6. [Install GitHub and its tools](https://review.docs.microsoft.com/help/contribute/contribute-get-started-setup-tools?branch=master#install-git-client-tools) + +7. [Install the Docs Authoring Pack](https://review.docs.microsoft.com/help/contribute/contribute-get-started-setup-tools?branch=master#install-the-docs-authoring-pack) + +## Set up your own version of the repo + +After you’ve created and set up your GitHub account and tools, you can create a personal version of your repo. This is where you will create your branches and make all your changes. + +### Fork the repository + +You need a local copy of the source files, so you can create pull requests from your fork to the production repository. + +#### To fork the repository + +1. Sign in to your GitHub account and go to https://github.com/microsoftdocs/windowsserverdocs-pr. + +2. Select **Fork**. + + ![Fork button highlighted on page](media/create-new-using-github/fork-button.png) + +3. Select your GitHub account as the fork location. + + ![Fork button highlighted on page](media/create-new-using-github/fork-location.png) + +### Clone the repository + +You need to clone the repo get a local copy of the repo on to your local device. + +#### To clone the repository + +1. Go to https://github.com/settings/developers, and then select **Personal access tokens** from the left pane. + +2. Select **Generate new token**, give your token a meaningful and unique name, select all the available scopes, and then select **Generate token**. + +3. Copy the token and put it somewhere safe. You’ll need this for the rest of the process and after you leave the page, you won’t be able to get back to it. + +4. Open a Git Bash command and change directories to where you want to store your repo. We recommend using, `C:\users\\Documents\GitHub`, because GitHub creates this directory by default. + +5. Type the following commands using your specific information, one at a time, to clone your repo and set up your remote branches: + + ```markdown + + git clone https://:@github.com//windowsserverdocs-pr.git + + cd windowsserverdocs-pr + + git remote add upstream https://:@github.com/MicrosoftDocs/windowsserverdocs-pr.git + + git fetch upstream master + ``` + +6. Run this command to make sure your remote is properly set up: + + `git remote -v` + +7. You should see something like this output: + + ```markdown + $ git remote -v + + origin https://github.com//windowsserverdocs-pr.git (fetch) + origin https://github.com//windowsserverdocs-pr.git (push) + upstream https://github.com/MicrosoftDocs/windowsserverdocs-pr.git (fetch) + upstream https://github.com/MicrosoftDocs/windowsserverdocs-pr.git (push) + ``` + + If your remote output doesn’t look like this, you can try again by first running `git remote remove upstream`. + +## Create a branch and a new article + +Follow these steps to create an article. + +### Create a new branch and a new file + +Before you can start to work on your content, you must create a new branch in your local repo. + +#### To create a new branch in Git Bash + +- Open Git Bash and type the commands (one at a time): + + ```markdown + cd windowsserverdocs-pr + + git checkout –B + + git push origin + ``` + + >[!Note] + >We highly recommend naming your branch something obvious and unique so you can find it again later. + + After the commands finish, you’ll be in your new branch and ready to create your new file. You only need to change into the windowsserverdocs-pr repo once per instance of your Git Bash. If you close Git Bash, you will need to change directories again after you open it. + +#### To create a new file in your branch + +1. Open Windows Explorer, go to your GitHub directory, and create a new text file in the folder structure. Your file name must be all lowercase and separated by hyphens. For example, _what-is-windows-server.md_. + + You must also change the file extension from .txt to .md. In the error message that appears, select **Yes** to save the file with the new file extension. + +2. Open Visual Studio Code and go to **File**, select **Open folder**, and then go to the GitHub location of the file you created in Step 1. + +3. From the **Explorer** pane, select your new file. + +4. Add your text to the page, and then select **File** > **Save**. + +### Preview your text + +After you add your text to your new file, you must preview your changes to make sure they appear correctly. + +#### To preview your text + +1. In Visual Studio Code, select either of the **Preview** buttons from the upper right-hand corner. + + ![preview button icon](media/create-new-using-github/preview-button-full-page.png): Switches to a full-page preview of your content. + + ![preview button icon](media/create-new-using-github/preview-button-side-by-side.png): Opens the preview page next to your working page, side-by-side. + +2. Make sure your article looks how you expect it to look. + + After you're sure it looks right, you can commit your changes create a pull request for publication. + +### Commit your changes + +After you make sure your text looks right, you can commit your changes to your local version of your repo. + +#### To commit your changes + +- Open Git Bash and type the commands (one at a time, removing the OPTIONAL tags): + + ```markdown + OPTIONAL: git status + + git add . + + git commit -m “public comment about what change is” + + OPTIONAL: git pull upstream master + + git push origin + + ``` + + The optional git status command shows you which files have been modified as part of this commit. The optional git pull upstream master pulls down the latest content changes from the MicrosoftDocs master branch, syncing your local content with the primary master content. This helps to show you any potential merge conflicts ahead of time so you can fix them before you get to the PR stage. + +### Submit a pull request for review and publication + +After you've completed your article, you must get approval from your writer (allow some time for this) for publication. + +#### To submit your pull request + +1. Go to https://github.com/MicrosoftDocs/windowsserverdocs-pr and select the **Pull requests** tab. + +2. In the **Reviewers** area of the right pane, select the gear icon, and then enter the _windowsservercontent_ alias for review. + + A member of the _windowsservercontent_ alias will review your changes or add comments about things that must be changed before merging can happen. + +3. Type **#sign-off** into the comments so that the reviewers know you’re handing off for both review and publishing. The **#sign-off** comment: + + - Updates the label for your pull request from **do-not-merge** to **ready-to merge**. + + - Lets the alias and writers know that you're ready to have your content reviewed. + + - Lets the admins know that after approval, your content is ready go live. + + >[!Important] + >After you add the #sign-off comment, a member of the windowsservercontent team will review the text and push it to master so it will go out with the next scheduled publish to live (10:30am and 3:30pm weekdays). + > + >If you don’t add #sign-off as a final comment to your PR, your content will remain in the queue without being pushed to Master and ultimately to Live. + +## Related information + +For more information about GitHub and the markdown language, see: + +### Git concepts + +* https://guides.github.com/introduction/git-handbook/ + +* https://guides.github.com/activities/forking/ + +* https://guides.github.com/introduction/flow/ + +* https://learngitbranching.js.org/ (Great for visual learners!) + +### Markdown + +* https://www.markdowntutorial.com/ diff --git a/Contributor-guide/edit-existing-using-github.md b/Contributor-guide/edit-existing-using-github.md new file mode 100644 index 0000000000..20642b62e7 --- /dev/null +++ b/Contributor-guide/edit-existing-using-github.md @@ -0,0 +1,131 @@ +--- +title: Edit an existing Windows Server article using GitHub and Visual Studio Code +description: How to edit an existing Windows Server-related articles, using GitHub and Visual Studio Code, as a Microsoft employee. +author: eross-msft +ms.author: lizross +ms.date: 05/06/2019 +--- + +# Edit an existing Windows Server article using GitHub and Visual Studio Code + +As a Microsoft employee, you can follow these instructions to edit an existing article and to create a new pull request for approval and publishing. + +You must still create a new branch for edits, but you don’t have to create a new .md file. Instead, you can just open Visual Studio Code and browse to the location of the folder or file. After you find the file you want to update, make your changes, preview your text, and then commit your changes. + +>[!Note] +>For information about how to create and set up your GitHub account, set up two-factor verification, and install and configure all the necessary tools, along with how to set up your own version of the repo, see the [Create new Windows Server articles using GitHub and Visual Studio Code](create-new-using-github.md) article. + +## Switch your repo and create a new branch + +Follow these steps to edit an existing article. + +### Create a new branch and locate the file you want to update + +Before you can start to work on your content, you must first change to the windowsserverdocs-pr repo and then locate the article you want to update. + +#### To create a new branch in Git Bash + +- Open Git Bash and type the commands (one at a time): + + ```markdown + cd windowsserverdocs-pr + + git checkout –B + + git push origin + ``` + + >[!Note] + >We highly recommend naming your branch something obvious and unique so you can find it again later. + + After the commands finish, you’ll be in your new branch and ready to edit your file. + +#### To locate your article and make your edits + +1. Open Visual Studio Code and go to **File**, select **Open folder**, and then go to the GitHub location of the folder that has the article you want to edit. + +2. From the **Explorer** pane, select the file. + +3. Update the information on the page, and then select **File** > **Save**. + +### Preview your text + +After you update the text, you must preview your changes to make sure they appear correctly. + +#### To preview your text + +1. In Visual Studio Code, select either of the **Preview** buttons from the upper right-hand corner. + + ![preview button icon](media/create-new-using-github/preview-button-full-page.png): Switches to a full-page preview of your content. + + ![preview button icon](media/create-new-using-github/preview-button-side-by-side.png): Opens the preview page next to your working page, side-by-side. + +2. Make sure your article looks how you expect it to look. + + After you're sure it looks right, you can commit your changes create a pull request for publication. + +### Commit your changes + +After you make sure your text looks right, you can commit your changes to your local version of your repo. + +#### To commit your changes + +- Open Git Bash and type the commands (one at a time, removing the OPTIONAL tags): + + ```markdown + OPTIONAL: git status + + git add . + + git commit -m “public comment about what change is” + + OPTIONAL: git pull upstream master + + git push origin + + ``` + + The optional git status command shows you which files have been modified as part of this commit. The optional git pull upstream master pulls down the latest content changes from the MicrosoftDocs master branch, syncing your local content with the primary master content. This helps to show you any potential merge conflicts ahead of time so you can fix them before you get to the PR stage. + +### Submit a pull request for review and publication + +After you've completed your updates, you must get approval from your writer (allow some time for this) for publication. + +#### To submit your pull request + +1. Go to https://github.com/MicrosoftDocs/windowsserverdocs-pr and select the **Pull requests** tab. + +2. In the **Reviewers** area of the right pane, select the gear icon, and then enter the _windowsservercontent_ alias for review. + + A member of the _windowsservercontent_ alias will review your changes or add comments about things that must be changed before merging can happen. + +3. Type **#sign-off** into the comments so that the reviewers know you’re handing off for both review and publishing. The **#sign-off** comment: + + - Updates the label for your pull request from **do-not-merge** to **ready-to merge**. + + - Lets the alias and writers know that you're ready to have your content reviewed. + + - Lets the admins know that after approval, your content is ready go live. + + >[!Important] + >After you add the #sign-off comment, a member of the windowsservercontent team will review the text and push it to master so it will go out with the next scheduled publish to live (10:30am and 3:30pm weekdays). + > + >If you don’t add #sign-off as a final comment to your PR, your content will remain in the queue without being pushed to Master and ultimately to Live. + +## Related information + +For more information about GitHub and the markdown language, see: + +### Git concepts + +* https://guides.github.com/introduction/git-handbook/ + +* https://guides.github.com/activities/forking/ + +* https://guides.github.com/introduction/flow/ + +* https://learngitbranching.js.org/ (Great for visual learners!) + +### Markdown + +* https://www.markdowntutorial.com/ \ No newline at end of file diff --git a/Contributor-guide/file-names-and-locations.md b/Contributor-guide/file-names-and-locations.md deleted file mode 100644 index 5cb4cae7e3..0000000000 --- a/Contributor-guide/file-names-and-locations.md +++ /dev/null @@ -1,70 +0,0 @@ - - - - -# File names and locations for Windows Server technical articles - -Knowing and following the rules helps you get your pull request accepted faster. - -+ [Rules] -+ [Pattern] -+ [File name approval] - -## Rules - -- All files must be in markdown and use the .md file extension. -- Keep the file names to 3-5 words if possible - 10 words is really too long for readability and SEO. -- Use lower case and only letters, numbers, and hyphens. -- No spaces or punctuation characters. Use a hyphen to separate words and numbers in the file name. -- Use the short form of action verbs, not the '-ing' form: `deploy-nano-server` not `Deploying-Nano-Server` -- Leave out small words, such as a, and, the, in, or. -- Spell words out; avoid unapproved or unnecessary acronyms in file names -- File names should be unique - instead of `overview.md` use `storage-spaces-overview.md` - -Acronyms and initialisms in file names - specific guidelines: - -- Follow existing Microsoft guidance for acceptable name abbreviations -- Industry-standard abbreviations are acceptable as necessary in file names. - -## Pattern - -Review the list of articles in the repository to get an idea of existing names. Here's the general pattern: - - **component-topic-title.md** - -For example, `storage-spaces-direct-overview.md` - -## File name approval - -When you submit a new file, pull request reviewers review the name and provide feedback via the pull request comment stream if changes are needed. The file name needs to be corrected before the pull request is accepted. Contributors can easily push the update to the pending pull request. - -## Folders in the repo - -Use the existing folder structure. Don't create folders without getting approval from a repository admin. Talk to them if you think you need a new folder. - -The GitHub repository should have a simple and relatively flat folder structure – \\\\ - for example storage\data-deduplication. Doing so has the following advantages: - - It’s very simple. - - It’s closer to how Azure.com works - - It makes it easy for writers/PMs to quickly find their topics – no need to dig around through other folders looking for where a particular technology is nested. - - It keeps the URL short, which is good for SEO and user experience, customers occasionally look at the URL for cues. - -## Changing case in file names - -Windows operating systems are case insensitive. If you need to change a file name to fix casing, it's better to make a change to the file contents, unless you're on a Linux or Mac. For example: - - biztalk-administration-and-Development-Task-List-in-BizTalk-Services --> biztalk-services-administration-and-development-task-list - -Use the `git mv` command to rename a file: -``` - git mv -``` - -### Contributors' Guide Links - -- [Index of guidance articles](./contributor-guide-index.md) - - - -[Rules]: #rules -[Pattern]: #pattern -[File name approval]: #file-name-approval diff --git a/Contributor-guide/git-steps-create-update-content.md b/Contributor-guide/git-steps-create-update-content.md deleted file mode 100644 index cd8532958b..0000000000 --- a/Contributor-guide/git-steps-create-update-content.md +++ /dev/null @@ -1,88 +0,0 @@ - - - - -# Git commands to create or update an article - ->!NOTE: These commands assume you've configured Github to specify the default repo where you pull files from. In Github terminology, where you pull files from is your *upstream*. Where you push files to is your *origin*. Based on how our repo and workflow are designed, your upstream should be set to our repo, which is under the Microsoft organization - https://github.com/Microsoft/WindowsServerDocs-pr and your origin should be your fork of this repo, under your own Github account. For example, Kathy's is https://github.com/KBDAzure/WindowsServerDocs-pr - ->To check your settings, type ```git config -l```. Look at the URLs to make sure they refer to location you intended. - -## Add or update an article - -Here's how to create a local branch, save your changes, and then push them to your remote fork. - -1. Start Git Bash (or the command-line tool you use for Git). - -2. Change to WindowsServerDocs-pr: - - cd WindowsServerDocs-pr - -3. It's best to keep your local Master branch and the remote Master branch in your fork in sync with the repo's Master branch. This can help save you a lot of frustration and lost time -- you're more likely to catch issues early and keep things in a good, known working state. Run: - - git checkout master - git pull upstream master - git push origin master - -4. Now you're ready to create a branch to do your daily or deliverable-based work in. The best way to create a local working branch from a release branch is to use to run: - - git checkout upstream/upstream-branch-name -b your-local-branch-name - - This creates the local branch directly from the upstream branch and helps you avoid merging the wrong files into your new local branch. For example, to create a working branch based on the ga-threshold branch, you could run a command like this: - - git checkout upstream/master -b working-11-18 - - If you're working on content that should be merged into branch that's not - -5. Add the local working branch to your fork: - - git push origin - -6. Create your new article or make changes to an existing article. Use Windows Explorer to open markdown files, and your markdown editor to create and edit files. For basic formatting help, see this [article](https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github/) in Github. - -7. Add required metadata and version info, according to [Metadata and product versioning](metadata-OSversioning-and-trademarks.md). - -8. Check status, then add and commit your changes: - - git status - - Review the results to make sure the files listed are the ones you changed. If ALL the files look accurate, run this command to add all of the files: - - git add . - git commit –m "" - - To add only the specific files (for example, if ```git status``` lists files that you don't want to submit), instead you MUST run: - - git add - git commit –m "" - - >[!IMPORTANT] - >The command ```git add .``` adds ALL pending changes reported by ```git status```. This means that if ```git status``` shows untracked updates that you don't want to add, use ```git add ``` instead. - -9. Update your local working branch with changes from upstream: - - git pull upstream master - -10. Push the changes to your fork on GitHub: - - git push origin - -## Submit your changes - -When you're ready to submit your content for staging, validation, and/or publishing, use the GitHub UI to create a pull request. - -When you open a pull request (PR), this triggers a test pass, builds the project and publishes to our internal staging site. It's okay to open a pull request that you're not ready to have merged because this is how you get a test pass and check your updates on the staging site. Build details and staging links are posted as comments to the PR. - -It's your responsibility to do the following **before you ask to have your changes merged**: - - Review build details to make sure it contains no errors. - - Review your updates on the staging site. - -After you've done this, indicate it by either: -- Adding the "ready-to-merge" label to the PR. \(Click **Labels** or the gear icon to the right of the comment stream in the PR.) -- Adding ready-to-merge as a comment and send email to the WSSC Pull Reviewers alias: wssc-pra - -The PR reviewer checks your changes and accepts the PR unless there are issues or questions. Feedback or requests to fix issues are added as comments. Review [Quality criteria for pull request review](contributor-guide-pr-criteria.md) to learn what's expected. - -## Publishing - -- Articles are published at around 10:00 AM and 3:00 PM Pacific Time, Monday-Friday. Keep in mind that a pull request reviewer needs time to review and accept your changes before they can merged. Changes must be merged to be picked up in the next scheduled publishing cycle. If you need an article published for a specific publication cycle, let a pull request reviewer know ahead of time. When your PR is accepted, your changes are merged into the repo and will be included in the next time publication run. It can take up to 30 minutes for articles to appear online after publishing. diff --git a/Contributor-guide/github-browser-updates.md b/Contributor-guide/github-browser-updates.md new file mode 100644 index 0000000000..c32e66b4ba --- /dev/null +++ b/Contributor-guide/github-browser-updates.md @@ -0,0 +1,54 @@ +--- +title: Edit existing Windows Server articles using a web browser and GitHub +description: How to make quick edits to the existing Windows Server documentation using a web browser and GitHub, as a Microsoft employee. +author: eross-msft +ms.author: lizross +ms.date: 05/02/2019 +--- + +# Update existing Windows Server articles using a web browser and GitHub + +The Microsoft Windows Server documentation set is open source and hosted on GitHub. This open source approach streamlines and improves communication between product engineers, content teams, and the customer. + +The user experience on [docs.microsoft.com/windows-server](https://docs.microsoft.com/windows-server) integrates [GitHub](https://github.com) workflows directly to make it even easier for you to contribute as a Microsoft employee. + +> [!IMPORTANT] +> All repositories that publish to docs.microsoft.com have adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) or the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/). Or contact [opencode@microsoft.com](mailto:opencode@microsoft.com), or [conduct@dotnetfoundation.org](mailto:conduct@dotnetfoundation.org) with any questions or comments. +> +> Minor corrections or clarifications to documentation and code examples in public repositories are covered by the [docs.microsoft.com Terms of Use](https://docs.microsoft.com/legal/termsofuse). New or significant changes generate a comment in the pull request, asking you to submit an online Contribution License Agreement (CLA) if you are not an employee of Microsoft. We need you to complete the online form before we can review or accept your pull request. + +## Quick edits to existing articles using GitHub and a web browser + +Quick edits streamline the process to report and fix small errors and omissions in documents. Despite all efforts, small grammar and spelling errors _do_ make their way into our published documents. + +1. Go to https://github.com/MicrosoftDocs/windowsserverdocs-pr/tree/master/WindowsServerDocs. + +2. Navigate to the article you want to edit, and then select the **Edit this file** button. + + ![Edit this file button](media/github-browser-updates/edit-this-file.png) + +3. Edit the topic, then scroll down to the bottom, briefly describe the changes, and then select **Commit changes**. + + ![Commit changes with title info](media/github-browser-updates/commit-changes.png) + +## Submit the pull request + +After you create your pull request, you must submit it for approval and publishing. + +### To submit your pull request + +1. On the **Open a pull request** page, update your commit message to make it more appropriate for a PR. For example: Fix typo in first paragraph. + +2. Make sure that only the commits and files you expect to be included are included. Also check that the PR goes to the correct branch in the upstream repository, either master (typically) or a release branch (occasionally). + +3. In the **Reviewers** area of the right pane, select the gear icon, and then enter _windowsservercontent_. A member of the alias will be on point to review your changes and either merge your pull request or add comments about things to change before merging. + +4. Select **Create pull request**. The new PR is linked to your working branch in your fork. Until the PR is merged, any new commits you push to the same working branch in your fork are automatically included in the PR. A new label is added to your pull request that says, **do-not-merge**. This simply means that your content is still in progress and shouldn't be reviewed or pushed to the live site. + +5. When you're ready for someone from the alias to review your content, you must add the text, **#sign-off** to the comments. This comment: + + - Updates the label for your pull request from **do-not-merge** to **ready-to merge**. + + - Lets the alias and writers know that you're ready to have your content reviewed. + + - Lets the admins know that after approval, your content is ready go live. \ No newline at end of file diff --git a/Contributor-guide/media/create-new-using-github/fork-button.png b/Contributor-guide/media/create-new-using-github/fork-button.png new file mode 100644 index 0000000000..690d885b58 Binary files /dev/null and b/Contributor-guide/media/create-new-using-github/fork-button.png differ diff --git a/Contributor-guide/media/create-new-using-github/fork-location.png b/Contributor-guide/media/create-new-using-github/fork-location.png new file mode 100644 index 0000000000..e4f036e8f1 Binary files /dev/null and b/Contributor-guide/media/create-new-using-github/fork-location.png differ diff --git a/Contributor-guide/media/create-new-using-github/preview-button-full-page.png b/Contributor-guide/media/create-new-using-github/preview-button-full-page.png new file mode 100644 index 0000000000..3bfc46592f Binary files /dev/null and b/Contributor-guide/media/create-new-using-github/preview-button-full-page.png differ diff --git a/Contributor-guide/media/create-new-using-github/preview-button-side-by-side.png b/Contributor-guide/media/create-new-using-github/preview-button-side-by-side.png new file mode 100644 index 0000000000..bf327dbbf4 Binary files /dev/null and b/Contributor-guide/media/create-new-using-github/preview-button-side-by-side.png differ diff --git a/Contributor-guide/media/create-new-using-github/preview-button.png b/Contributor-guide/media/create-new-using-github/preview-button.png new file mode 100644 index 0000000000..029a8c7094 Binary files /dev/null and b/Contributor-guide/media/create-new-using-github/preview-button.png differ diff --git a/Contributor-guide/media/github-browser-updates/commit-changes.png b/Contributor-guide/media/github-browser-updates/commit-changes.png new file mode 100644 index 0000000000..5ffd63682a Binary files /dev/null and b/Contributor-guide/media/github-browser-updates/commit-changes.png differ diff --git a/Contributor-guide/media/github-browser-updates/edit-this-file.png b/Contributor-guide/media/github-browser-updates/edit-this-file.png new file mode 100644 index 0000000000..4597a77e31 Binary files /dev/null and b/Contributor-guide/media/github-browser-updates/edit-this-file.png differ diff --git a/Contributor-guide/metadata-OSversioning-and-trademarks.md b/Contributor-guide/metadata-OSversioning-and-trademarks.md deleted file mode 100644 index f052cd5043..0000000000 --- a/Contributor-guide/metadata-OSversioning-and-trademarks.md +++ /dev/null @@ -1,54 +0,0 @@ -# Metadata and version identifiers - -Here's what you need to know about trademarks, versioning, and metadata for the articles in windowsserverdocs-pr repository. Article authors are responsible for making sure their articles adhere to these standards and requirements. - -## Trademarks -Don't use trademark symbols after product references in articles in the technical library. They aren't required because technet.microsoft.com, docs.microsoft.com, and other official Microsoft publishing channels include a [Trademark](https://www.microsoft.com/trademarks) footer link to a list of Microsoft trademarks. That link fulfills the legal requirement. For background, see guidance from [CELA](https://microsoft.sharepoint.com/sites/LCAWeb/Home/Copyrights-Trademarks-and-Patents/Trademarks/Trademark-List-and-Usage), under "websites" and the Microsoft Writing Style Guide [Copyrights and trademarks](https://worldready.cloudapp.net/Styleguide/Read?id=2700&topicid=26696) page, under "Webpages on Microsoft.com" - -## Versioning -Several types of versioning apply to the articles in this repo: - -- Versioning that indicates the product version that an article applies to is done two ways: - - Manually on a single line in the article so it's visible as text on a published article. - - By metadata, described below. -- Source content versioning is handled through Github's history on the file. - -## Metadata structure and format - -- Put Metadata at the top of the file, above the H1 heading. -- Separate the block from the rest of the file contents by using only three dashes in the first and last lines of the block. Don't put any other text on those lines. -- Put each metadata name/value pair on a separate line. -- Use one of the following syntax patterns, depending on whether the metadata requires predefined values or accepts custom values. - - --- - name1: predefined-value - name2: "my custom value" - --- - -## Metadata names and values - -Certain metadata is required for all files published as articles in the TechNet technical library, while other metadata is recommended but not required. In some cases, only certain values are allowed for a specific piece of metadata. - -|Name|Value| -|---|---| -|title|Custom value that matches the H1 heading. Determines what shows in the browser tab.| -|description|Shows in search results and affects SEO. Include appropriate keywords but keep length to less than 160 characters.| -|author|Github alias of the primary author of the article| -|ms.author|MSFT alias of the article's author or content developer responsible for the technology area covered in the article.| -|ms.date|Date of last content update. Don't update for changes to metadata only. Use the format mm/dd/yyyy.| -|ms.prod|Identifies the Windows Server version for BI reporting, based on a predefined [value](https://microsoft.sharepoint.com/teams/STBCSI/Insights/_layouts/15/WopiFrame.aspx?sourcedoc=%7b7A321BF1-0611-4184-84DA-A0E964C435FA%7d&file=WEDCS_MasterList_CSIValues.xlsx&action=default&IsList=1&ListId=%7b46B17C8A-CD7E-47ED-A1B6-F2B654B55E2B%7d&ListItemId=969).| -|ms.technology|Identifies the technology area for BI reporting, based on a predefined [value](https://microsoft.sharepoint.com/teams/STBCSI/Insights/_layouts/15/WopiFrame.aspx?sourcedoc=%7b7A321BF1-0611-4184-84DA-A0E964C435FA%7d&file=WEDCS_MasterList_CSIValues.xlsx&action=default&IsList=1&ListId=%7b46B17C8A-CD7E-47ED-A1B6-F2B654B55E2B%7d&ListItemId=969)| -|ms.asset|GUID that identifies the article across all locales for BI reporting. Articles migrated from earlier authoring systems already have this. For articles created in Github, use a tool such as [https://guidgenerator.com/](https://guidgenerator.com/).| - -## Troubleshooting - -Metadata that appears at the top of a published article happens when the source file has formatting errors. Some common errors are: - -- Missing the triple hyphens at the first and last lines of the block, or the wrong number of hyphens. -- Metadata doesn't follow the required syntax: \:\\ - -Check your file for these and any other obvious errors, then submit a PR to publish the updated file. If you're stuck, email the PR reviewers alias: wssc-pra@microsoft.com - -## See also -Metadata used in this repo is based on metadata used in Content Services & International \(CSI\). More info, including optional metadata, is available at [http://aka.ms/skyeye/meta](http://aka.ms/skyeye/meta). -For business intelligence resources, see the CSI BI team's [wiki](https://microsoft.sharepoint.com/teams/STBCSI/Insights/Selfserve%20BI%20wiki/Self-serve%20BI%20wiki.aspx). \ No newline at end of file diff --git a/Contributor-guide/metadata-requirements-for-articles.md b/Contributor-guide/metadata-requirements-for-articles.md new file mode 100644 index 0000000000..fad69e1eb7 --- /dev/null +++ b/Contributor-guide/metadata-requirements-for-articles.md @@ -0,0 +1,53 @@ +--- +title: Add the required metadata tags to your Windows Server-related article +description: A list of the information you must add as metadata tags to the top of your Windows Server-related articles. The required tags are subject to change, based on both your reporting and team requirements. +author: eross-msft +ms.author: lizross +ms.date: 05/06/2019 +--- + +# Add the required metadata tags to your Windows Server-related article + +At the top of every article, there is specific metadata that must be included for tracking and SEO purposes. The required tags are subject to change, based on reporting requirements. However, you should be notified if you need to add/remove any fields. + +It should look like this, including the three hyphens (---) at the top and bottom: + +```markdown + +--- +title: The title of the article should go here. This is used in SEO and search results. + +description: A description for the article should go here. This is used in search results, to provide users with information about whether the article has the information they’re looking for. + +ms.prod: Use this specific text, windows-server-threshold + +ms.reviewer: The Microsoft alias for the primary PM for the feature/functionality + +author: Your GitHub alias + +ms.author: Your Microsoft alias + +manager: Your manager’s Microsoft alias + +ms.date: Date of change (MM/DD/YYYY) + +--- + +``` + +## Example + +```markdown + +--- +title: What is Windows Admin Center? +description: Learn about the Windows Admin Center, a locally-deployed, browser-based management tool set that lets you manage your Windows Servers with no Azure or cloud dependency. +ms.prod: windows-server-threshold +ms.reviewer: alainch +author: danielle-github +ms.author: danielle +manager: alainch +ms.date: 07/06/2019 +--- + +``` \ No newline at end of file diff --git a/Contributor-guide/rename-or-retire.md b/Contributor-guide/rename-or-retire.md deleted file mode 100644 index 19d99200bc..0000000000 --- a/Contributor-guide/rename-or-retire.md +++ /dev/null @@ -1,90 +0,0 @@ -# Rename or delete an article - -Before you rename or delete an article, you need to follow this process to avoid or reduce the number of broken links. Customers hate broken links and aren't shy about sounding off when they hit one. Note that renaming or deleting an article is the last step in this process, not the first. - - -## Step 1: Manage inbound links - -Determine if there are any non-Microsoft inbound links to your content, such as blogs, forums, and other content on the web. Contact blog owners to change these links, and remove or update links from forum posts. Web analytics tools can help identify high traffic inbound links you might need to manage in this way. - -## Step 2: Remove all crosslinks to the article from the WindowsServerDocs-pr repository - -1. Refresh your local branch – run `git pull upstream `, ie to refresh from master, run `git pull upstream master` - -2. Scan the WindowsServerDocs-pr folder to find articles that have a link to the article you want to rename or retire, then update the articles to remove the links or replace them with links to another article. 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: - - a. Start Windows PowerShell. - - b. At the PowerShell prompt, change into the WindowsServerDocs-pr folder: - - `cd WindowsServerDocs-pr\WindowsServerDocs-pr` - - c. Run a command to list all files that contain a link to the article to rename or delete: - - `Get-ChildItem -Recurse -Include *.md* | Select-String "" | group path | select name` - - To send the list of file names to a text file (in this case, named psoutput.txt), run: - - `Get-ChildItem -Recurse -Include *.md* | Select-String "" | group path | select name | Out-File C:\Users\\psoutput.txt` - -3. Add and commit all your changes, push them to your fork, and open a pull request. For instructions, see [Git commands to create or update an article](git-steps-create-update-content.md). - -## Step 3: Update FWLinks - -Check the FWLink tool for any FWLinks that point to the article. Point any FWLinks at replacement content; if you are not on the alias that owns the link, join it. If the owners won't update the link, file a ticket with MSCOM to have the link changed. More info - [internal wiki](http://sharepoint/sites/azurecontentguidance/wiki/Pages/Manage%20inbound%20links%20to%20retired%20topics.aspx). - -## Step 4: Remove crosslinks to the article from table of contents - -Work with the person who maintains the ToC.md file. This file populates the left-hand table of contents in the technical library. If you don't know who to contact, send email to wssc-pra@microsoft.com. - -## Step 5: Add redirects -If you're renaming ore deleting a file, add a redirect so that existing links don't break: - -1. Leave the old file in the existing location with the existing file name. -2. Replace the content in the file with this piece of metadata: - ``` - --- - redirect_url: - --- - ``` - \ is the full URL to a different location or is the path+filename to a different topic in the same OPS repo. - - For example - this would be the whole file: - - ``` - --- - redirect_url: ../../failover-clustering/whats-new-in-failover-clustering - --- - ``` - -3. After creating a PR for the redirect, click the links in the comments for the PR - if the redirect works you should get to the target topic. - -## Step 6: Rename or delete the article - -If you're not using a redirect, do this step after you've completed the previous steps and all affected articles are published. If you are using a redirect, renaming or deleting the article would undo this and cause a broken link. -To rename a file, simply rename it in the file system, then add, commit and push the change, and then open a pull request. -To delete a file, first you need to know that it doesn't work to just delete a file from your file system because this is a source control system and it needs to know you intended to do this. Otherwise your deleted files will probably reappear. -There are two ways to do this: - -- File system and git: - Delete the file from the file system. Then from your git tool, run one of the following ```Git add -A``` | ```Git add --all``` | ```Git add -u``` -- Just git: - Run ```git rm foo.md``` - - More info [http://stackoverflow.com/questions/2047465/how-can-i-delete-a-file-from-git-repo](http://stackoverflow.com/questions/2047465/how-can-i-delete-a-file-from-git-repo) and [https://git-scm.com/docs/git-rm](https://git-scm.com/docs/git-rm) - -## Step 7: Find and fix straggler broken links - -Use the content QA tool to find broken links that the previous steps didn't catch, then remove or fix the links. - -## Step 8: Remove cached pages from search engines - -Go to these web pages to remove cached web pages from search engines: -[Bing](https://www.bing.com/webmaster/tools/content-removal?rflid=1) -[Google](https://www.google.com/webmasters/tools/removals?pli=1) - - -### Contributors' guide links - -- [Index of guidance articles](./contributor-guide-index.md) - diff --git a/Contributor-guide/tools-and-setup.md b/Contributor-guide/tools-and-setup.md deleted file mode 100644 index 2f09923327..0000000000 --- a/Contributor-guide/tools-and-setup.md +++ /dev/null @@ -1,23 +0,0 @@ - - - - -# Install and set up tools for authoring in GitHub - -Instructions are available on Windows Server writing team's site - [Contributors start here](https://microsoft.sharepoint.com/teams/WindowsServerContent/SitePages/Contributors%20start%20here.aspx). - -After you're set up, see the other [articles](Contributor-index.md) in this guide to learn to contribute to this repo. - diff --git a/Contributor-guide/ws-template.md b/Contributor-guide/ws-template.md deleted file mode 100644 index 5c414a7032..0000000000 --- a/Contributor-guide/ws-template.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -# required metadata -title: [ARTICLE TITLE] -description: -author: [GITHUB USERNAME] -ms.author: [MICROSOFT ALIAS] -ms.date: [DATE] -ms.topic: article -ms.prod: windows-server-threshold -ms.technology: -ms.localizationpriority: [high/medium/low] ---- - -# Metadata and Markdown Template - -This OPS template contains examples of Markdown syntax, as well as guidance on setting the metadata. To get the most of it, you must view both the [raw Markdown](https://raw.githubusercontent.com/Microsoft/WindowsServerDocs-pr/master/Contributor-guide/ws-template.md?token=AG1vEhARRHNLtPgKXP35BGjNZGajKOArks5YLNIwwA%3D%3D) and the [rendered view](https://github.com/Microsoft/WindowsServerDocs-pr/blob/master/Contributor-guide/ws-template.md). (The raw Markdown shows the metadata block, while the rendered view does not.) - -When creating a Markdown file, you should copy this template to a new file, fill out the metadata as specified below, set the H1 heading above to the title of the article, and delete the content. Anything in CAPS in square brackets requires your attention. - - -## Metadata - -The full metadata block is above. Some key notes: - -- You **must** have a space between the colon (:) and the value for a metadata element. -- Colons in a value (for example, a title) break the metadata parser. In their place, use the HTML encoding for a colon of `:` (for example, `"title: Azure Rights Management: the basics | Azure RMS"`). -- **title**: This title will appear in search engine results. -- **author**: The author field should contain the **GitHub username** of the author, not their alias. -- **ms.prod**, **ms.technology**: Use "windows-server-threshold" for ms.prod (or w10 if you're using this template to create content for Windows 10). Talk to your CX contact to get the ms.technology value. - -## Basic Markdown, GFM, and special characters - -All basic and GitHub-flavored Markdown is supported. For more information on these, see: - -- [Baseline Markdown syntax](https://daringfireball.net/projects/markdown/syntax) -- [GitHub-flavored Markdown (GFM) documentation](https://guides.github.com/features/mastering-markdown) - -Markdown uses special characters such as \*, \`, and \# for formatting. If you wish to include one of these characters in your content, you must do one of two things: - -- Put a backslash before the special character to "escape" it (for example, \\\* for a \*) -- Use the [HTML entity code](http://www.ascii.cl/htmlcodes.htm) for the character (for example, \&\#42\; for a *). - -## Headings - -Headings should be done using atx-style, that is, use 1-6 hash characters (#) at the start of the line to indicate a heading, corresponding to HTML headings levels H1 through H6. Examples of first- and second-level headers are used above. - -There **must** be only one first-level heading (H1) in your topic, which will be displayed as the on-page title. - -Second-level headings will generate the on-page TOC that appears in the "In this article" section underneath the on-page title. - -### Third-level heading -#### Fourth-level heading -##### Fifth level heading -###### Sixth-level heading - -## Text styling - -*Italics* - -**Bold** - -~~Strikethrough~~ - -## Links - -### Internal Links - -To link to a header in the same Markdown file, view the source of the published article, find the ID of the head (for example, `id="blockquote"`), and link using # + id (for example, `#blockquote`). - -- Example: [Blockquotes](#blockquote) - -To link to a Markdown file in the same repo, use [relative links](https://www.w3.org/TR/WD-html40-970917/htmlweb.html#h-5.1.2), including the ".md" at the end of the filename. - -- Example: [Tips and gotchas](tips-gotchas.md) -- Example: [Tools and setup for contributors](../readme.md) - -To link to a header in a Markdown file in the same repo, use relative linking + hashtag linking. - -- Example: [Deleting files](tips-gotchas.md#deleting-files) - -### External Links - -To link to an external file, use the full URL as the link. - -- Example: [GitHub](http://www.github.com) - -If a URL appears in a Markdown file, it will be transformed into a clickable link. - -- Example: http://www.github.com - -## Lists - -### Ordered lists - -1. This -1. Is -1. An -1. Ordered -1. List - - -#### Ordered list with an embedded list - -1. Here -1. comes -1. an -1. embedded - 1. Miss Scarlett - 1. Professor Plum -1. ordered -1. list - - -### Unordered Lists - -- This -- is -- a -- bulleted -- list - - -##### Unordered list with an embedded list - -- This -- bulleted -- list - - Mrs. Peacock - - Mr. Green -- contains -- other - 1. Colonel Mustard - 1. Mrs. White -- lists - - -## Horizontal rule - ---- - -## Tables - -In almost every instance, use MD formatting for tables. While HTML tables provide more flexibility we DO NOT use them in our content. If you have an HTML table in your article, we will not merge that article. - -| Tables | Are | Cool | -| ------------- |:-------------:| -----:| -| col 3 is | right-aligned | $1600 | -| col 2 is | centered | $12 | -| col 1 is default | left-aligned | $1 | - - -## Code - -### Generic codeblock - -Indent code four spaces for generic codeblock coding. - - function fancyAlert(arg) { - if(arg) { - $.docs({div:'#foo'}) - } - } - - -### Codeblocks with language identifier - -Use three backticks (```) + a language ID to apply language-specific color coding to a code block. Here is the entire list of [GitHub Flavored Markdown (GFM) language IDs](https://github.com/jmm/gfm-lang-ids/wiki/GitHub-Flavored-Markdown-(GFM)-language-IDs). - -##### C♯ - -```c# -using System; -namespace HelloWorld -{ - class Hello - { - static void Main() - { - Console.WriteLine("Hello World!"); - - // Keep the console window open in debug mode. - Console.WriteLine("Press any key to exit."); - Console.ReadKey(); - } - } -} -``` -#### Python - -```python -friends = ['john', 'pat', 'gary', 'michael'] -for i, name in enumerate(friends): - print "iteration {iteration} is {name}".format(iteration=i, name=name) -``` -#### PowerShell - -```powershell -Clear-Host -$Directory = "C:\Windows\" -$Files = Get-Childitem $Directory -recurse -Include *.log ` --ErrorAction SilentlyContinue -``` - -### Inline code - -Use backticks (`) for `inline code`. - -## Blockquotes - -> The drought had lasted now for ten million years, and the reign of the terrible lizards had long since ended. Here on the Equator, in the continent which would one day be known as Africa, the battle for existence had reached a new climax of ferocity, and the victor was not yet in sight. In this barren and desiccated land, only the small or the swift or the fierce could flourish, or even hope to survive. - -## Images - -### Static Image - -![this is the alt text](../windowsserverdocs/get-started/media/wsbanner.png) - -### Linked Image - -[![alt text for linked image](../windowsserverdocs/get-started/nano.png)](../windowsserverdocs/get-started/getting-started-with-nano-server.md) - -## Alerts - -### Note - -> [!NOTE] -> This is NOTE - -### Warning - -> [!WARNING] -> This is WARNING - -### Tip - -> [!TIP] -> This is TIP - -### Important - -> [!IMPORTANT] -> This is IMPORTANT - diff --git a/README.md b/README.md index 435940770e..490dc21ebd 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,59 @@ -## Microsoft Open Source Code of Conduct +# Windows Server Documentation -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). -For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. +Welcome to the open source documentation of Microsoft Windows Server. Please review this README file to understand how you can assist in contributing to the Windows Server documentation. -# WindowsServerDocs-pr +## Getting Started + +Contributing to open source is more than just providing updates, it's also letting us know when there is an issue. Read our [Contributing guidance](https://github.com/MicrosoftDocs/windowsserverdocs-pr/blob/master/contributor-guide.md) to find out more. + +## Prerequisites + +You've decided to contribute, that's great! + +Contributing to the documentation first requires you to have a GitHub account. If you don't have an account, follow the instructions to [set up a GitHub account](https://review.docs.microsoft.com/help/contribute/contribute-get-started-setup-github?branch=master). + +After you have your GitHub account, you'll also need to download and install the following tools: + +- [Visual Studio Code](https://review.docs.microsoft.com/help/contribute/contribute-get-started-setup-tools?branch=master#install-visual-studio-code) + +- [Git client](https://git-scm.com/download) + +- [Docs Authoring Pack extension for Visual Studio Code](https://review.docs.microsoft.com/help/contribute/contribute-get-started-setup-tools?branch=master#docs-authoring-pack) + +## WindowsServerDocs-pr This repo is actively managed and includes the source for Windows Server content published to [docs.microsoft.com](https://docs.microsoft.com): -- [Windows Server 2019](https://docs.microsoft.com/en-us/windows-server/get-started-19/get-started-19) -- [Windows Server 2016](https://docs.microsoft.com/en-us/windows-server/get-started/server-basics) -- [Essentials Server 2016 and Essentials Server 2019](https://docs.microsoft.com/en-us/windows-server-essentials/get-started/get-started) -- [Microsoft Hyper-V Server 2016](https://docs.microsoft.com/en-us/windows-server/get-started/server-basics) +- [Windows Server 2019](https://docs.microsoft.com/windows-server/get-started-19/get-started-19) +- [Windows Server 2016](https://docs.microsoft.com/windows-server/get-started/server-basics) +- [Essentials Server 2016 and Essentials Server 2019](https://docs.microsoft.com/windows-server-essentials/get-started/get-started) + +## How can I contribute? + +There are a couple of ways to contribute to the documentation, review the sections below to find out which one is right for you. + +### Lightweight editing in the GitHub browser + +Follow the [guidance to make quick edits using the GitHub web browser](./Contributor-guide/github-browser-updates.md). This guidance is intended only for small changes to existing content. If you want to make larger changes, you must follow the process using GitHub and Visual Studio Code. + +### Creating new content using GitHub and Visual Studio Code + +Follow the [guidance to create new articles using GitHub and Visual Studio Code](./Contributor-guide/create-new-using-github.md). + +### Editing existing content using GitHub and Visual Studio Code + +Follow the [guidance to update existing articles using GitHub and Visual Studio Code](./Contributor-guide/edit-existing-using-github.md). + +## Reporting Bugs and Suggesting Enhancements + +Please use the Feedback tool at the bottom of any article to submit bugs and suggestions. +![Feedback tool at the bottom of any article](media/feedback-area.png) -To make a small update, simply edit the file and submit a pull request. Check out [Editing existing Windows professional documentation](https://docs.microsoft.com/en-us/windows/whats-new/contribute-to-a-topic) for more details. +## License -For internal, Microsoft contributors - Info on how to add or update content, minimum quality standards, formatting help and more is available in the [Contributor's Guide](https://aka.ms/windowsauthoring). +Please refer to [LICENSE](https://github.com/MicrosoftDocs/windowsserverdocs-pr/blob/master/LICENSE), [LICENSE-CODE](https://github.com/MicrosoftDocs/windowsserverdocs-pr/blob/master/LICENSE-CODE) and [ThirdPartyNotices](https://github.com/MicrosoftDocs/windowsserverdocs-pr/blob/master/ThirdPartyNotices) for all Licensing information. +## Code of Conduct +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. \ No newline at end of file diff --git a/media/compare-changes.png b/media/compare-changes.png new file mode 100644 index 0000000000..52d063af3b Binary files /dev/null and b/media/compare-changes.png differ diff --git a/media/contribute-link.png b/media/contribute-link.png new file mode 100644 index 0000000000..4cf685e54e Binary files /dev/null and b/media/contribute-link.png differ diff --git a/media/feedback-area.png b/media/feedback-area.png new file mode 100644 index 0000000000..fd5e8c3f0c Binary files /dev/null and b/media/feedback-area.png differ diff --git a/media/pencil-icon.png b/media/pencil-icon.png new file mode 100644 index 0000000000..82fe7852dd Binary files /dev/null and b/media/pencil-icon.png differ diff --git a/media/preview-changes.png b/media/preview-changes.png new file mode 100644 index 0000000000..2e8c0b0bda Binary files /dev/null and b/media/preview-changes.png differ diff --git a/media/propose-file-change.png b/media/propose-file-change.png new file mode 100644 index 0000000000..aedbc07b16 Binary files /dev/null and b/media/propose-file-change.png differ