MSDN Documentation Style Guide

1. Introduction

Welcome to the Microsoft Developer Network (MSDN) Documentation Style Guide. This guide provides a comprehensive set of rules and best practices for creating clear, consistent, and high-quality documentation for Microsoft products and services. Adhering to this guide ensures that our documentation is accessible, user-friendly, and reflects the Microsoft brand.

The goal of MSDN documentation is to empower developers and IT professionals by providing them with the information they need to effectively use and integrate Microsoft technologies. This guide focuses on aspects of content creation that directly impact the user experience.

2. Design Principles

Our documentation design is guided by the following principles:

• Clarity: Information should be easy to understand, unambiguous, and precisely worded.
• Conciseness: Avoid unnecessary jargon, wordiness, and redundancy. Get straight to the point.
• Consistency: Use uniform terminology, formatting, and structure throughout all documentation.
• Accuracy: Information must be technically correct and up-to-date.
• Accessibility: Content should be usable by everyone, including individuals with disabilities.
• Task-Orientation: Focus on helping users achieve their goals.

3. Content Guidelines

3.1 Writing Style

Employ a direct and informative writing style. Use active voice whenever possible. Sentences should be clear and grammatically correct. Avoid colloquialisms and overly casual language.

Do: "The function returns a string."

Don't: "You'll get a string back from this function."

3.2 Voice and Tone

The primary voice should be neutral and objective. The tone should be professional, helpful, and encouraging. Address the reader directly using "you" when appropriate for instructional content.

Example: "To start, you need to install the SDK."

3.3 Terminology

Use standard Microsoft product names and technical terms. Maintain a glossary of key terms and ensure consistent usage across all documentation.

Refer to the official Microsoft Terminology Collection for guidance.

3.4 Acronyms and Abbreviations

Spell out acronyms and abbreviations the first time they appear in a document, followed by the acronym in parentheses. After the first mention, use the acronym exclusively.

Example: "Application Programming Interface (API)"

Exception: Widely recognized acronyms like HTML, CSS, JS do not need to be spelled out.

4. Formatting

4.1 Headings

Use headings to structure content logically and improve readability. Hierarchy is important:

• <h1>: Main page title.
• <h2>: Major section titles.
• <h3>: Sub-section titles.
• <h4>: Further sub-divisions.

Headings should be descriptive and concise.

4.2 Paragraphs

Keep paragraphs relatively short, focusing on a single idea. Use line breaks to visually separate paragraphs.

4.3 Lists

Use unordered lists (<ul>) for items without a specific order and ordered lists (<ol>) for steps or items that require a specific sequence.

Unordered List Example:

• Item one
• Item two
• Item three

Ordered List Example:

1. First step
2. Second step
3. Third step

4.4 Code Formatting

Use <pre> and <code> tags for displaying code snippets. Highlight keywords and syntax where appropriate. Ensure code is properly indented and readable.

function greet(name) {
    if (!name) {
        return "Hello, stranger!";
    }
    return `Hello, ${name}!`;
}

console.log(greet("World"));
// Output: Hello, World!

4.5 Tables

Use tables for presenting structured data, such as parameters, return values, or configuration options.

4.6 Images

Images should be used judiciously to illustrate concepts or steps. Ensure images are optimized for web performance and are relevant to the content.

5. Accessibility

5.1 Alt Text

All meaningful images must have descriptive alternative text (alt attribute) for screen readers and users who cannot view images.

Example: <img src="diagram.png" alt="Diagram showing data flow from source to destination.">

5.2 Keyboard Navigation

Ensure all interactive elements are navigable and operable using a keyboard alone. This includes links, buttons, form controls, and custom widgets.

6. Examples

6.1 Code Example

Use the pre and code tags as demonstrated in section 4.4. Provide clear, runnable, and relevant code samples.

6.2 API Description

When describing APIs, clearly list:

• Endpoint URL
• HTTP Method (GET, POST, PUT, DELETE)
• Request Headers
• Request Body (with schema and examples)
• Response Codes (with descriptions)
• Response Body (with schema and examples)

Use tables to detail parameters and responses.