News

New VS Code Tool Eases Writing Microsoft Documentation

A couple years ago, Microsoft revamped its developer documentation experience, turning to an open model in which anyone could contribute to the docs.microsoft.com site. Now, a new Visual Studio Code extension has been published to make that easier.

The Docs Authoring Pack launched on the Visual Studio Code Marketplace last week, providing a collection of extensions to aid with authoring Markdown files, which are famously used for GitHub project README.md introductory files. Markdown lets developers easily write documentation in plain text, which is converted to structurally valid XHTML or HTML files easily presentable on the Web.

Writing Markdown in Action
[Click on image for larger, animated GIF view.] Writing Markdown in Action (source: Microsoft).

According to an announcement blog post published last Friday, the first iteration of the VS Code extension package includes three extensions:

  • Docs Markdown This provides Markdown authoring assistance including formatting text, inserting lists and tables, inserting links to other content, and adding images and other assets. Unlike other Markdown editors, Docs Markdown supports custom Markdown extensions for docs.microsoft.com, such as alerts and code snippets.
  • DocFX This provides a limited docs.microsoft.com-specific Markdown preview to help see what a Markdown file will look like when published.
  • markdownlint This is described as a popular Markdown linter created by David Anson to help ensure Markdown follows best practices.

These tools will let Visual Studio and other Microsoft-centric developers contribute to Microsoft' Docs site, which was announced in June 2016 as a more modern approach, eclipsing the infrastructure supporting the TechNet and MSDN documentation sites that were described as being "built on a 10-15 year-old brittle codebase with an archaic publishing and deployment system that was never designed to run on the cloud."

The Docs Contributor Guide says developers can contribute to the documentation by:

Microsoft hopes all those tasks will be easier with the new VS Code extension, which was climbing toward 500 installs as of this writing and is also hosted on GitHub.

About the Author

David Ramel is an editor and writer for Converge360.

comments powered by Disqus

Featured

  • Visual Studio 2019 for Mac v8.9 Ships with .NET 6 Preview 1 Support

    During its Ignite 2021 online event for IT pros and developers this week, Microsoft shipped Visual Studio 2019 for Mac v8.9, arriving with out-of-the-box support for .NET 6 Preview 1, which the company also released recently.

  • Analyst: TypeScript Now Firmly in Top 10 Echelon (Ruby, Not So Much)

    RedMonk analyst Stephen O'Grady believes TypeScript has achieved the rare feat of firmly ensconcing itself into the top 10 echelon of his ranking, now questioning how high it might go.

  • Black White Wave IMage

    Neural Regression Using PyTorch: Training

    The goal of a regression problem is to predict a single numeric value, for example, predicting the annual revenue of a new restaurant based on variables such as menu prices, number of tables, location and so on.

  • Microsoft Ships Visual Studio 2019 v16.9 Servicing Baseline Release

    Microsoft is urging enterprises and professional coders to standardize on the new Visual Studio 2019 v16.9, a servicing baseline release that's guaranteed to receive official support for an extended period.

Upcoming Events