Documentation Style Guide

Introduction

This document outlines the style guidelines for all documentation published under the Microsoft Developer Network (MSDN) brand. Adhering to these guidelines ensures consistency, clarity, and a high-quality user experience across all our technical content.

Our goal is to provide developers with accurate, accessible, and easy-to-understand information that empowers them to build amazing applications with Microsoft technologies.

Typography

We use a clean and readable font hierarchy to ensure content is scannable and digestible.

Primary Font: Segoe UI

Segoe UI is our primary typeface for all documentation. It offers excellent readability across various screen sizes and resolutions.

Headings: Use appropriate heading levels (H1, H2, H3) to structure content logically.
Body Text: Maintain a comfortable line height and paragraph spacing.
Emphasis: Use <strong> for strong importance and <em> for emphasis. Avoid excessive use of bold or italics for non-semantic purposes.

Color Palette

Our color palette is designed for accessibility and a professional look and feel.

Primary Color

#0078d4 (MSDN Blue)

Used for links, active states, primary buttons, and key graphical elements.

Secondary Color

#f2f2f2 (Light Gray)

Used for backgrounds, dividers, and subtle UI elements.

Text Colors

#333 (Dark Gray) for body text.

#1a1a1a (Near Black) for headings.

Ensure sufficient color contrast for all text and interactive elements to meet accessibility standards.

Layout and Spacing

Consistent layout and generous spacing improve readability and reduce cognitive load.

Grid System: Content is typically presented in a two-column layout (sidebar navigation and main content) on larger screens.
Whitespace: Ample whitespace around elements (headings, paragraphs, images, code blocks) is crucial for visual appeal and clarity.
Margins and Padding: Standardize margins between sections and padding within UI elements.

UI Elements +

Tables

Use tables for presenting structured data in a clear, tabular format.

Element	Description	Example
`<div>`	A generic container.	`<div class="container">`
`<button>`	An interactive button.	`<button>Click Me</button>`

Accordions

Use accordions to progressively disclose information.

Collapsible Section

Click the header to expand or collapse the content.

Code Samples +

Code samples should be clear, concise, and well-formatted.

Inline Code

For short code snippets within sentences, use the <code> tag, like this: var x = 10;.

Code Blocks

For longer code samples, use the <pre> tag with <code> inside.


function greet(name) {
  console.log(`Hello, ${name}!`);
}

greet("World");

Language Highlighting

While not implemented here, consider using syntax highlighting libraries for better readability of code blocks.

Example Usage

C# Example

A simple C# class definition.


public class User
{
    public string Name { get; set; }
    public int Age { get; set; }
}

Voice and Tone

Our documentation should be:

Authoritative: Provide accurate and reliable information.
Clear: Use straightforward language, avoiding jargon where possible or explaining it when necessary.
Concise: Get to the point efficiently.
Helpful: Focus on enabling the user to accomplish their tasks.
Professional: Maintain a respectful and expert tone.