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.
[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 at Converge 360.