New Vocabularies for Technical Publishing

Three new vocabularies have been proposed as the result of a collaborative effort by several Technology companies. They are specifically for use with Technical Articles, API reference documentation, and Code.

These proposed vocabularies will improve search engines’ understanding of documentation with technical content, and thus greatly increase the discoverability of this documentation.

The following snippets highlight the potential of these new vocabularies.

TechArticle

Informs which product version the content is referring to

This content is for version 4; and the current version is 4.5.

<meta itemprop="aboutProduct" content=".Net Framework 4.0" />

<meta itemprop="currentProduct" content=".Net Framework 4.5" />

Informs where to get more information on the overall concept

This content on “Hyper-V Server 8 Beta” is about the broader concept of virtualization:

<span itemprop="about" itemscope itemtype="http://schema.org/CreativeWork">

<meta itemprop="name" content="Virtualization"/>

<metaitemprop="url" content="http://technet.microsoft.com/en-US/virtualization"/>

</span>

Maps content to the audience’s intent

This is content that describes how to do something:

itemprop="genre" content="How-to"

This content describes steps for troubleshooting:

itemprop="genre" content="Troubleshooting"

APIReference

Disambiguates version and usage

This content refers to a managed assembly:itemprop="programmingModel" content="Managed" itemprop="assembly" content="mscorlib.dll" />

Defines platform category

This reference documentation applies to the phone platform:

itemprop="aboutProduct" content=".Net Framework 4.5"

itemprop="targetPlatform" content="phone"

This reference documentation applies to the desktop platform:

itemprop="aboutProduct" content=".Net Framework 4.5"

itemprop="targetPlatform" content="desktop"

Code

Defines section of content as sample code

This Code is a C++ sample inserted in an article:

<div itemscope itemtype="http://schema.org/Code">

<meta itemprop="name" content=" Allocating Memory from a NUMA Node "/>

<meta itemprop="sampleType" content=" inline"/>

<div itemprop="programmingLanguage">

C++

</div>

</div>

This is a full visual studio solution in an MSDN Code Gallery:

<div itemscope itemtype="http://schema.org/Code">

<meta itemprop="codeRepository" content="http://code.msdn.microsoft.com/Web-Authentication-d0485122/view/SourceCode" />

<meta itemprop="sampleType" content="Visual Studio solution(SLN)" />

</div>

We would like this community’s feedback concerning the above proposals.

Thanks!

Charlie Jiang and Kenley Lamaute