MSDN Online: Content Submission Standards for Product Documentation Sets

MSDN Publishing
September 2003

Before You Start

Introduction
List of All Submission Standards for Product Documentation Sets
Detailed Submission Standards for Product Documentation Sets
Further Reading

Introduction

Before submitting your content to MSDN, please be familiar with the Writing Guidelines for MSDN. The standards for product documentation set submissions to MSDN have been created to ensure your content is posted as intended in all desired product locations. Following these standards will reduce the number of bugs assigned to your content as a result of posting it to multiple product locations.

Go to Handing Off Product Documentation Sets for details about handoff procedures.

List of All Submission Standards for Product Documentation Sets

The following list includes all the areas that must be handled before submitting product documentation sets to MSDN. You can jump to detailed explanations of each standard listed below.

Internal Review
All Submitted Content Must Be Final
A-Keywords
Attributes
Search Requirements
Formatting
Index Keywords
Table of Contents
Geopolitical Issues
Custom Scripts
Folder Structure
Copyright
Topic Not Found References
Other Known Issues
HXS/HXI Requirements
Stop List
File Versioning

Detailed Submission Standards for Product Documentation Sets

Internal Review

It is expected that all content has gone through an internal review by the contributing team and that the team has agreed that their content works as expected—no broken links, JavaScript works as expected, and so on.

All Submitted Content Must Be Final

Please do not submit content that contains blank pages or that might be substantially revised.

A-Keywords

All topics must include a unique A-keyword per topic to allow cross-HXS links (HxLinks) to work. If you do not include an A-keyword, other groups cannot link to your content. To do this, include the following in your topics' XML sections:

<xml> 
<MSHelp:Keyword Index="A" Term="unique_A_keyword"/> 
</xml>

Note Because XML is case-sensitive, make sure to use the correct XML entities in the XML headings of your files. The term <mshelp:keyword index="a" term="unique_A_keyword"/> will not be picked up by our tools.

If you are not certain that your keyword is unique, consult the A-Keyword Lookup Tool (http://rputools/hxlinks/hxlinks.aspx) that has been created to search the database for these files. You can also use the results to create your ALinks to other MSDN Library content.

Attributes

MSDN requires that all content be tagged with a core set of attributes:

Information Type
DocSet (if applicable)
Product Version (if applicable)
Devlang Version (if applicable)
Technology Version (if applicable)
TargetOS
TargetCPU

The complete set of available attributes and values can be found at MSDN Guide to Content Attribution. When you prepare your content for handoff to MSDN, the attribute metadata should be authored as an XML island within the header of your pages.

Please follow this format:

<xml> 
<MSHelp:Attr Name="name" Value="value"/> 
</xml>

Note Because XML is case-sensitive, make sure to use the correct XML entities in the XML headings of your files. The term <mshelp:keyword index="a" term="unique_A_keyword"/> will not be picked up by our tools.

Search Requirements

The following search requirements will help enhance the discoverability of your content on the MSDN Web site. For further information, see Applying Search Tags for MSDN Content. Please make sure each documentation set has the following:

Descriptive title (80 characters or less) for each documentation set. This title needs to be included in the HxC so that it appears correctly in Search results. For example, "C++ Language Reference."
Unique, descriptive title (80 characters or less) for each topic placed within the page in an XML island. This is the title that will appear in the results list for search. For example, a descriptive title would appear like this in your HTML:
```
<MSHelp:RLTitle Title="Standard Compliance Issues in Visual C++"/>
```
Unique summary/abstract for each topic within the documentation set (255 characters or less). Each topic within a document set must have the following HTML tag:
```
<META NAME="DESCRIPTION" CONTENT="page abstract">
```
The HXS must include a unique title that will be used in index and full text search location fields. To do this, include the following in your HXC's HelpCollection element:
```
Title = "Your Title" 
```

This is the description that will appear under the title in the search engine's list of results. In order to improve search relevance for customers, it's very important to make the information descriptive and accurate. Also, remember that the words within the description itself are used to help rank the page within search results so be sure that important key words are included. If no descriptive title for a topic is available, you should use a generic description in its place.

Example: <meta name="description" content="Find everything you need to evaluate, deploy, use, update, and troubleshoot Microsoft Office XP.">

This is a required tag for the MSCOM search engine and including meaningful descriptions will significantly improve the discoverability of your content.

Formatting

When possible, please follow the formatting guidelines found in Using the MSDN Template.

As a minimum, font type must be Verdana 9 or 10 point.
Links to the Web must open up a new browser. Please make sure your code includes Target="_new" for these links.

Index Keywords

Index keywords must be authored correctly using the K-index:

If possible, there should be no empty parent index entries—index entries that do not return at least one topic.
Cross-reference entries should take the user to another index entry, not to a topic.
Incorrect:
Do not include the following in a topic:
```
<MSHelp:Keyword Index="K" Term=".bmp files (See also bitmaps)"/>
```
Correct:
Create a separate K-index HXK file compiled into your HXS that includes cross-reference entries in this format:
```
<Keyword Term=".bmp files"> 
   <Keyword Term="(See also bitmaps)" Ref="bitmaps"/> 
</Keyword> 
<Keyword Term=".jpg files See .jpeg files" Ref=".jpeg files"/> 
```
You must supply both an HXS and an HXI and a full text index. To do this, include the following in your HXC's CompilerOptions element:
```
CreateFullTextIndex = "Yes" 
CompileResult = "HxiHxs" 
```

Note In order for A-keywords to be picked up in your documents, an A-keyword index should be called in your HxC file. The HxC must contain these two lines of text:

<KeywordIndexDef File="Alinks.HxK"/>
<ItemMoniker Name="!DefaultAssociativeIndex" ProgId="HxDs.HxIndex" InitData="A"/>

You can name your ALink index whatever you choose, but it must correspond with the name used for the KeywordIndexDef File. Most commonly, users name their A-keywords index Alinks.HxK or ALinkIndex.HxK.

For further indexing guidelines, refer to Microsoft Indexing Guidelines for Developer Documentation (http://mssts/IndexQA/Lists/Guidelines/AllItems.htm).

Empty TOC nodes should be avoided as much as possible; in Visual Studio they are considered a bug. An empty TOC node does not have a page associated with it.
All topics should be included in a TOC unless there is a compelling reason to not do so.
All topics must include a TOC Title and a Results List title (for the results returned by Full Text Search, Index, etc.). To do this, include the following in your topics' XML sections:
```
<xml> 
<MSHelp:TOCTitle Title="topic title"/> 
<MSHelp:RLTitle Title="results list title"/> 
</xml> 
```

Geopolitical Issues

For a list of geopolitical issues that must be considered, please see the GeoPolitical Strategy Web Site (http://gpsweb/) and PoliCheck English Terms Reference Guide (http://gpsweb/tools/policheck/DisplayTerms.asp?LCID=9).

Custom Scripts

The MSDN Online Library does currently support custom scripts. If you wish to include custom .css and .js files, it is your team's responsibility to have these files working correctly on the online site.

You may work with the MSDN Build Team before your drop to run test builds to ensure that your .js or .css files will work properly within the MSDN Library.

Folder Structure

MSDN maintains your folder hierarchy as it is received from you on both the MSDN Online Library and the MSDN Subscriptions Library.

Copyright

The HXS must include a file property copyright. To do this, include the following in the HelpCollection element of your HXC:

Copyright = "&#x00A9; 2003 Microsoft Corporation.
All rights reserved."

This results in:

© 2003 Microsoft Corporation. All rights reserved.

You can change the date to whatever is appropriate for your product.

In the MSDN Online Library all pages will contain both the product team's copyright notice and the MDSN default copyright, unless otherwise requested. All pages will carry the MSDN footer and toolbar. This is required by our site structure and cannot be removed.

Topic Not Found References

The default MSDN Online Library version of a Topic Not Found page will display if you do not specify your own Topic Not Found page on your HxLinks (aka, ALinks). The MSDN page is preferred.

If you do want to specify your own Topic Not Found page on your HxLinks, you must prevent your Topic Not Found page from returning hits in Full Text search. This is accomplished by adding the following element in the <head> section of your topics:

<ms-help:nosearch>

Other Known Issues

Ensure your .htm is properly coded. It must contain body tags, title tags, double quotes around attributes, and so forth.
Please provide a master HXT or a list of HXS/HXI pairs in the order they should appear in the TOC in your Product Studio bug.
File names cannot include spaces.
MSDN owns and manages the Product Studio bug-tracking templates. There will be different templates for all MSDN Library product locations.
No quotes in title tags in TOC files. (Single quotes or escaped characters are acceptable.). For instance, the title The Effect of the "Blaster" Virus on Office 2003 is not acceptable because it contains quotes. Users may use the " tag for quotes. This is a requirement of our site structure.
The Content Managers will be the gatekeepers for approval of content for MSDN Online.
The MSDN Quarterly PM will be the final gatekeeper for content that may not get contributor approval on the CD. He has the power to request that contributors revise the content or face removal of it.

HXS/HXI Requirements

Only HXS/HXI files will be accepted. We must have an HXS/HXI pair; we cannot accept either file separate from the other.
We require compiled HXS/HXI using the Microsoft Help 2.0 (Havana) Compiler. We do not need your source files.
The HXS/HXI must contain all project files (HXT, HXC, and so on) so that if we were to decompile it, we could recompile it. The HXT file should live at the root of your project.
HXS/HXI must contain a valid TOC, have index entries, and have no code that is not compatible with IE 5.5 or later.
The HXS and HXI must both have the same date-time stamp.

Stop List

Please use the new MSDN full text search stop list (\\ppgbuild01\public\stoplist\msdnFTSstop_Unicode.stp).

To do this, include the following in your HXC's CompilerOptions element:

StopWordFile="msdnFTSstop2.stp"

File Versioning

The HXS/HXI must include a file property version number. You may version the file according to your product team's versioning scheme, provided it fits into this format: X.XX.XXXX.XXXX. Visual Studio's version number looks like this: 7.00.date.time with Date and Time set by the VS build Jdate and 24-hour clock time (e.g., 7.00.9200.1530). To set the version number, include the following in your HXC's HelpCollection element:

FileVersion = "X.XX.XXXX.XXXX"

The version number must be incremental: that is, every drop you make must have a later version number than the previous drop. This is vital to allow for adequate Test/QA support, such as verifying that the HXS/HXI MSDN Library is installing is the latest one you dropped.

e.g., 1.0.0.1 > 1.0.5.2 > 1.0.2789.8138

The following types are not acceptable:

0.0.0.0, 1.0.0.0, 7.0.0.0