visualstudio-docs is where the Visual Studio pages are actually written

The pages on Learn are generated from this tree

The repository is described as the home of the official documentation for Visual Studio, and it contains the source files for the Visual Studio technical documentation, with the topics published at the Visual Studio product family documentation on Microsoft Learn. The distinction between the repository and the site is the first thing to understand, because it decides where an edit has to be made. A page you read on Learn is a build artefact, and the article you want to change is a Markdown file here, and the pipeline in between is what the rest of this repository is about. The repository was moved on June 23, 2017 from the earlier vsdocs location, which is a small historical note but a useful one, because the old URLs still resolve and the redirect files described later are part of why. The licence is CC BY 4.0 for the content, with a separate LICENSE-CODE file and a ThirdPartyNotices directory for material that is not covered by that licence.

Which documentation is not in this repository

The scope is narrower than a reader might assume, and the README is explicit about where the rest of the Visual Studio documentation lives. The documentation for Visual Basic and Visual C# is located in the dotnet docs repository, under its docs directory, and the Visual C++ documentation is located in the C++ docs repository, which is MicrosoftDocs/cpp-docs. That is a useful division to know before you spend an afternoon on a pull request against the wrong repository, and it also explains the shape of the tree here, which carries the topics that are specific to the IDE rather than to a language. The repository has separate top-level directories for several of those areas, including bridge/, docker/, gamedev/, mac/, scripting-docs/ and docs/ at the top level.

Feature folders, and the media rule inside each one

The organisation is by feature area rather than by product version. Several feature areas of Visual Studio have their own folders in the repository, the debugger folder holds topics on debugging, the ide folder holds topics on the Visual Studio integrated development environment, and so forth. Inside each of those folders sits a /media subfolder, and the README states that the /media subfolder in each folder contains the art files for the topics. That is a convention with a purpose. Screenshots in a documentation set are not decoration, they are load-bearing content, and a rule that says the images for a topic live next to the topic, in a predictable place, is what makes it possible for a writer to add an illustration without knowing the repository's history, and for a reviewer to check that a changed screenshot has been updated in the right folder. It is also the sort of convention that only survives if the tooling expects it, which is where the DocTune configuration in this repository comes in.

One redirect map per IDE version, and a script that sorts them

The top-level entries show a redirect system with more files than a documentation repository would normally have. There are separate redirection files for IntelliCode, for the mac documentation, for subscriptions, for Visual Studio 2015 and for Visual Studio 2017, alongside the main.openpublishing.redirection.json, and a publish configuration in.openpublishing.publish.config.json. Each of those is a URL map, and the reason there is one per IDE version is that the same topic has a different URL in different product releases, so a reader following an old link to a 2015 article has to land on the right page rather than on a 404 or on the current version of something else. The repository even ships a helper for maintaining them, sort-redir.py at the root, which suggests the entries are large enough to need keeping in a canonical order, which is what happens when redirects accumulate over years. The whole scheme is the answer to a problem that documentation repositories are usually bad at, which is that URLs are part of the public interface and people have them in bookmarks, in issue trackers and in other people's articles.

DocTune, the publish config and the what is new file

The publishing machinery is visible in three places. The .docutune/ directory is the configuration for the documentation tooling that the Learn site uses, which is where the conventions of the tree are declared, including the media rule and the metadata each article carries. The .openpublishing.publish.config.json is the configuration that describes the publication itself, and the .whatsnew.json file sits next to it, which is how a release of Visual Studio introduces what has changed, since a documentation set for a product that ships every few weeks needs a mechanism for saying what is new without editing dozens of pages by hand. The .localization-config file and the presence of a mac/ directory show the other side of the same coin, since Microsoft Learn serves the documentation in many languages and the localisable pieces are marked rather than guessed. None of this is documentation content, and all of it is why the repository has configuration files at the root rather than only articles in folders.

Contributing is a pull request with a lint rule set

The contribution path is the ordinary one, and the tooling around it is visible. The README welcomes contributions to help improve the Visual Studio docs, and says that all the articles in the repository use GitHub-flavored markdown. There is a CONTRIBUTING.md with the detail, a pull_request_template.md and an ISSUE_TEMPLATE.md at the root, and a .markdownlint.json that defines the markdown rules an article has to satisfy, which is the difference between a documentation repository that accepts a pull request and one that merges it without an editing round. A .github/ directory holds the workflows, and SECURITY.md covers how to report a security problem in the content, which for a documentation set is a real concern, because a wrong instruction in a security article is a vulnerability with a documentation URL. The code of conduct is the Microsoft Open Source Code of Conduct, with the FAQ and the [email protected] contact given. For a writer, the practical sequence is to find the article, check the folder convention, fix it in the file, and open the pull request against the repository that actually owns the topic.

Feedback moved to the page, and the open question it leaves

One change is worth noting because it changes where you should send a problem. The Learn site is changing how it receives feedback on the documentation, and the new way is already available by clicking the feedback icon at the top right of each article, or immediately following an article, with a link to the announcement of the new way to give feedback on Microsoft Learn. That is a meaningful change for a repository like this, because the feedback icon is the channel the site now points readers to, rather than the repository's issue tracker. The gap the README does not close is what happens to a piece of feedback that arrives through the new channel, whether it reaches a maintainer who can act on it. That question matters for anyone who plans to rely on the site for accuracy, because a documentation set that is corrected only when somebody files an issue is a documentation set that can be wrong for a long time, and the rule for a reader is the same either way, to check the date on an article and to report a problem through the channel that is in front of you.

Editorial conclusion

visualstudio-docs is the place to work if you have spotted an error in the Visual Studio documentation, because the published pages are generated from it and a pull request reaches the site through the same pipeline, and because the folder layout makes a small fix easy to place. It is not a repository to fork for your own documentation, since the build, the redirect scheme and the DocTune setup are tied to Microsoft's publishing system, and the Visual Basic, Visual C# and Visual C++ pages are not here at all. Before you open a pull request, read CONTRIBUTING.md, check that the topic belongs in this repository rather than the dotnet or C++ ones, and look at whether the file you are editing has an existing redirect entry, because a renamed topic has to keep its old URL working and that map is maintained by hand.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-4.0
3. MicrosoftDocs/visualstudio-docs on GitHub
4. README