|
1 | | -# Contributing |
| 1 | +# Contribute to Visual Studio documentation |
2 | 2 |
|
3 | | -Thank you for your interest in contributing to the Visual Studio documentation! |
| 3 | +Thank you for taking the time to contribute to the Visual Studio docs. |
4 | 4 |
|
5 | | -In this topic, you'll see the basic process for adding or updating content in the [Visual Studio documentation site](https://docs.microsoft.com/visualstudio). |
| 5 | +This guide covers some general topics around contributing and refers out to the docs.microsoft.com [contributors guide](https://docs.microsoft.com/contribute) for more detailed explanations. |
6 | 6 |
|
7 | | -In this topic, we'll cover: |
| 7 | +## Code of conduct |
8 | 8 |
|
9 | | -* [Process for contributing](#process-for-contributing) |
10 | | -* [Guidance checklist](#guidance-checklist) |
11 | | -* [Building the docs](#building-the-docs) |
12 | | -* [Contributing to samples](#contributing-to-samples) |
13 | | -* [Contributor License Agreement](#contributor-license-agreement) |
| 9 | +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 [[email protected]](mailto:[email protected]) with any additional questions or comments. |
14 | 10 |
|
15 | | -## Process for contributing |
| 11 | +## How can I contribute? |
16 | 12 |
|
17 | | -**Step 1:** Open an issue describing the article you wish to write and how it relates to existing content. |
18 | | -The content inside the **docs** folder is organized into sections that are organized by content area (e.g., debugger). Try to determine the correct folder for your new content. Get feedback on your proposal. |
| 13 | +There is a variety of ways to contribute to the documentation. Review the sections below to find out which one is right for you. |
19 | 14 |
|
20 | | -You can skip this first step for small changes. |
| 15 | +### Report bugs or suggest enhancements |
21 | 16 |
|
22 | | -**Step 2:** Fork the `MicrosoftDocs/visualstudio-docs` repo. |
| 17 | +Please use the feedback tool at the bottom of any article to submit bugs and suggestions. |
23 | 18 |
|
24 | | -**Step 3:** Create a `branch` for your article. |
| 19 | + |
25 | 20 |
|
26 | | -**Step 4:** Write your article. |
| 21 | +### Quick edit in GitHub |
27 | 22 |
|
28 | | -If it's a new topic, you can use this [template file](./styleguide/template.md) as your starting point. It contains the writing guidelines and also explains the metadata required for each article, such as author information. |
| 23 | +Follow the guidance for [quick edits to existing documents](https://docs.microsoft.com/contribute/#quick-edits-to-existing-documents) in the contributors guide. |
29 | 24 |
|
30 | | -Navigate to the folder that corresponds to the TOC location determined for your article in step 1. |
31 | | -That folder contains the Markdown files for all articles in that section. If necessary, create a new folder to place the files for your content. |
| 25 | +### Larger edits |
32 | 26 |
|
33 | | -For images and other static resources, add them to the subfolder called **media**. If you are creating a new folder for content, add a media folder to the new folder. |
34 | | - |
35 | | -Be sure to follow the proper Markdown syntax. See the [style guide](./styleguide/template.md) for more information. |
36 | | - |
37 | | -### Example structure |
38 | | - |
39 | | - docs |
40 | | - /debugger |
41 | | - debugging-installed-app-package.md |
42 | | - /media |
43 | | - debugging-installed-app-package.png |
44 | | - |
45 | | -**Step 5:** Submit a Pull Request (PR) from your branch to `MicrosoftDocs/visualstudio-docs/master`. |
46 | | - |
47 | | -If your PR is addressing an existing issue, add the `Fixes #Issue_Number` keyword to the commit message or PR description, so the issue can be automatically closed when the PR is merged. For more information, see [Closing issues via commit messages](https://help.github.com/articles/closing-issues-via-commit-messages/). |
48 | | - |
49 | | -The Visual Studio team will review your PR and let you know if the change looks good or if there are any other updates/changes necessary in order to approve it. |
50 | | - |
51 | | -**Step 6:** Make any necessary updates to your branch as discussed with the team. |
52 | | - |
53 | | -The maintainers will merge your PR into the master branch once feedback has been applied and your change looks good. |
54 | | - |
55 | | -On a certain cadence, we push all commits from master branch into the live branch and then you'll be able to see your contribution live at https://docs.microsoft.com/visualstudio/. |
56 | | - |
57 | | -## DOs and DON'Ts |
58 | | - |
59 | | -Below is a short list of guiding rules that you should keep in mind when you are contributing to the .NET documentation. |
60 | | - |
61 | | -- **DON'T** surprise us with big pull requests. Instead, file an issue and start a discussion so we can agree on a direction before you invest a large amount of time. |
62 | | -- **DO** read the [style guide](./styleguide/template.md) and [voice and tone](./styleguide/voice-tone.md) guidelines. |
63 | | -- **DO** use the [template](./styleguide/template.md) file as the starting point of your work. |
64 | | -- **DO** create a separate branch on your fork before working on the articles. |
65 | | -- **DO** follow the [GitHub Flow workflow](https://guides.github.com/introduction/flow/). |
66 | | -- **DO** blog and tweet (or whatever) about your contributions, frequently! |
67 | | - |
68 | | -> [!NOTE] |
69 | | -> You might notice that some of the topics are not currently following all the guidelines specified here and on the [style guide](./styleguide/template.md) as well. We're working towards achieving consistency throughout the site. Check the list of [open issues](https://github.com/dotnet/docs/issues?q=is%3Aissue+is%3Aopen+label%3Aguidelines-adherence) we're currently tracking for that specific goal. |
70 | | -
|
71 | | -## Building the docs |
72 | | - |
73 | | -The documentation is written in [GitHub Flavored Markdown](https://help.github.com/categories/writing-on-github/) and built using [DocFX](https://dotnet.github.io/docfx/) and other internal publishing/building tools. It is hosted at [docs.microsoft.com](https://docs.microsoft.com/dotnet). |
74 | | - |
75 | | -If you want to build the docs locally, you need to install [DocFX](https://dotnet.github.io/docfx/); latest versions are the best. |
76 | | - |
77 | | -There are several ways to use DocFX, and most of them are covered in the [DocFX getting started guide](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html). |
78 | | -The following instructions use the [command-line based](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html#2-use-docfx-as-a-command-line-tool) version of the tool. |
79 | | -If you are comfortable with other ways listed on the link above, feel free to use those. |
80 | | - |
81 | | -**Note:** Currently DocFX requires the .NET Framework on Windows or Mono (for Linux or macOS). We hope to port it to .NET Core in the future. |
82 | | - |
83 | | -You can build and preview the resulting site locally using a built-in web server. Navigate to the core-docs folder on your machine and type the following command: |
84 | | - |
85 | | -``` |
86 | | -docfx -t default --serve |
87 | | -``` |
88 | | - |
89 | | -This starts the local preview on [localhost:8080](http://localhost:8080). You can then view the changes by going to `http://localhost:8080/[path]`, such as http://localhost:8080/articles/welcome.html. |
90 | | - |
91 | | -**Note:** the local preview currently doesn't contain any themes at the moment so the look and feel won't be the same as in the documentation site. We're working towards fixing that experience. |
92 | | - |
93 | | -# Contributing to samples |
94 | | - |
95 | | -For now, include required sample code as inline code blocks in your article. The repo has a codesnippets folder, but this is not ready for public contributions. |
| 27 | +Review the guidance for [pull requests](https://docs.microsoft.com/contribute/how-to-write-workflows-major#pull-request-processing) in the contributors guide. |
0 commit comments