News

Want to Get Started in Open Source? Try Improving Visual Studio Documentation

• By David Ramel
• 07/19/2018

One of the questions often seen in programming forums is how to get started with contributing to open source projects. While survey after survey points to the growing popularity of the open source movement (and skyrocketing demand for open source skills), actually dipping your toes into the community waters seems daunting to many.

Answers to those forum questions -- along with many blog posts and how-to articles -- often include advice to start with something small, like improving documentation.

Along those lines, Microsoft's Kraig Brockschmidt recently put out a renewed call to invite community participation by contributing to the documentation for the Visual Studio IDE and Visual Studio Code editor.

While VS Code is well known as the open source, lightweight cross-platform counterpart to the full-blown .NET-centric Visual Studio IDE, many developers might not know that Visual Studio's documentation is also an open source project on GitHub.

"We're delighted to receive contributions from the community in both docsets, and actively monitor pull requests," Brockschmidt said in a recent post (which was mainly about new Python tutorials).

In keeping with the aforementioned advice to start small, Brockschmidt invited all manner of community efforts. "Truly, no contribution is too small," he said. "As the content developer who manages these docsets, I very much appreciate anyone who takes the time to fix a typo, correct an error, or otherwise make the docs better! Your contribution doesn't have to be perfect, either: we'll take the time to do the necessary editing and formatting."

The Visual Studio documentation on GitHub lists 367 contributors, while the VS Code documentation lists 349 contributors.

And, indeed, exploring the docs proves there's no contribution too small, as one VS Code "grammar" fix simply involved changing the capitalization of an "e.g." reference because it started out a new sentence. That contributor, going by the handle of "ahmadawais," has a history of such small typographical and grammar fixes, including unsplitting split infinitives.

Brockschmidt pointed out that volunteer contributions to Visual Studio and VS Code documentation can begin simply by clicking on the Edit icon that appears in the right-hand top corner of each article.

"Those links take you straight into the GitHub repository for that article, where you can make edits, see the history, and enjoy all the other GitHub goodness," he said.

Along with providing a good introduction to GitHub and open source in general, contributing to documentation might be a good start to improving one's resume, as multiple articles have indicated employers see open source involvement as a plus, demonstrating collaborative behavior and serving -- in the case of more advanced contributions -- as a means to show off technical chops.

In fact, the aforementioned jobs report indicated the demand for open source skills is so high that nearly half of hiring manages responding to the survey said their organization are supporting open source projects solely for the purpose of recruiting hard-to-find talent.

Documentation contributions are also needed by many other organizations beyond Microsoft. For example, another survey, this one by GitHub Inc. last year, indicated the growing open source movement is plagued by poor documentation. One of the key insights of that survey was listed as: "Documentation is highly valued, frequently overlooked, and a means for establishing inclusive and accessible communities."

Key documentation-related findings as listed by GitHub include:

• Incomplete or outdated documentation is a pervasive problem, observed by 93 percent of respondents, yet 60 percent of contributors say they rarely or never contribute to documentation. When you run into documentation issues, help a maintainer out and open a pull request that improves them.
• Many people participate in open source on the job, where confidence in the terms of use is critical. Unsurprisingly, licenses are by far the most important type of documentation to both users and contributors: 64 percent say an open source license is very important in deciding whether to use a project, and 67 percent say it is very important in deciding whether to contribute.
• Documentation helps create inclusive communities. Documentation that clearly explains a project's processes, such as contributing guides and codes of conduct, is valued more by groups that are underrepresented in open source, like women.
• Nearly a quarter of the open source community reads and writes English less than ‘very well.' When communicating on a project, use clear and accessible language for people who didn't grow up speaking English, or read less-than-fluently.

Microsoft maintains a Contributing guide for those who want to help out with Visual Studio or VS Code documentation.