Practical authoring conventions for documentation systems, structured docs, links, code, includes, Markdown and related technical-writing mechanics.
Adding GIF Image Resources in docfx.json records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Automating Code Validation in Documentation records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Avoiding Custom Layouts With Learn Columns records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Avoiding Horizontal Scrollbars in Code Blocks records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Avoiding HTML Tables in Microsoft Learn Markdown records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Avoiding IDE Screenshots for Code Examples records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Avoiding Inline HTML in Microsoft Learn records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Avoiding Inline Styling in Headings records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Avoiding Inline Styling in Link Text records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Avoiding Lettered Lists in Learn Markdown records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Avoiding Nested Include Files records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Choosing nameWithType and fullName in Microsoft Learn XRef Display Text records a distinct Microsoft Learn XRef authoring decision and consolidates tightly coupled syntax choices so the public guide stays useful without fragmenting one task into thin pages.
Clearly Labeling Bad Code Examples records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Displaying an Entire Referenced Code File records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Encoding or Replacing Smart Quotes in Learn Markdown records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Escaping Angle Brackets in Learn Markdown records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Escaping Special Characters in No-Loc Strings records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Escaping Underscores in Microsoft Learn Image Alt Text records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Finding and Preserving Microsoft Learn XRef UIDs records a distinct Microsoft Learn XRef authoring decision and consolidates tightly coupled syntax choices so the public guide stays useful without fragmenting one task into thin pages.
The strings ft, in, and oz function as compact unit symbols in NIST conversion material. They are useful after numbers in technical or tabular measurement notation, while the spelled-out unit names remain clearer in prose when space is not constrained. Punctuation and symbol treatment should follow the governing technical or house style.
Formatting Data Matrix Tables for Microsoft Learn records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Formatting Database Table and Column Names records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Formatting Git Repository and Branch Names records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Formatting Nonclickable URLs in Technical Documentation records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Formatting Nonlocalized Resource Names records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Formatting NuGet Package Names records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Highlighting Key Lines in Code Blocks records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Indenting Learn Bullet Continuations by Two Spaces records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Indenting Learn Numbered-List Continuations by Three Spaces records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Keeping Include Media Outside Includes Folders records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Keeping Learn Columns to Basic Markdown records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Keeping Sensitive Information Out of HTML Comments records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Keeping Separate Media Files for Learn Includes records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Limiting Alerts in Microsoft Learn Articles records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Linking From Microsoft Learn Includes With Longer Relative Paths records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Linking From Microsoft Learn Selectors records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Linking to Microsoft Learn Headings With Bookmark Links records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Linking to Microsoft Learn XRef Method Pages and Overloads records a distinct Microsoft Learn XRef authoring decision and consolidates tightly coupled syntax choices so the public guide stays useful without fragmenting one task into thin pages.
Linking to Third-Party Sites From Microsoft Learn records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Linking to YML Files for Split Microsoft Learn Articles records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
List indentation serves both alignment and hierarchy. Hanging indents help wrapped lines align with item text, while deeper indentation can mark nested items; the exact implementation depends on the authoring system.
Nested lists express hierarchy by placing child items under a parent item. In Microsoft Learn Markdown, indentation defines the nesting level, and ordered and unordered list types can be combined; exact markup behavior remains platform-specific.
Not Applying Code Style to Linked Reference Text records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Percent-Encoding XRef UID Special Characters in Microsoft Learn records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Preferring In-Repository Snippet References records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Referencing Code From Another Repository records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Referencing Named Code Snippets by ID records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Requiring a Space After Learn Heading Hashes records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Selecting Line Ranges in Referenced Code Snippets records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Setting Image Localization Scope records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Understanding Include Rendering on GitHub records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Absolute URLs for Non-Documentation Microsoft Properties records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Approved Language Tags in Fenced Code Blocks records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Using Automatic Borders on Learn Images records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Block Includes for Reusable Sections records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Capitalized INCLUDE Syntax in Microsoft Learn records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Checklists at Article Boundaries records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Complex Images With Long Descriptions records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Consistent Bullet Markers in Learn Markdown records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Consistent Bullets in Learn Markdown records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Custom Link Text With Markdown-Style XRefs records a distinct Microsoft Learn XRef authoring decision and consolidates tightly coupled syntax choices so the public guide stays useful without fragmenting one task into thin pages.
Using Fenced Code Blocks for Longer Code records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Using File-Relative Links for Microsoft Learn Articles records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using H2 Headings for Learn Navigation records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Icon Images Without Alt Text records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Inline Includes Inside Sentences records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Interactive Code Snippets in Documentation records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Using Jupyter Notebook Snippets in Documentation records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Using Multi-Selectors in Learn Markdown records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Next-Step Action Buttons in Microsoft Learn records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Nonlocalized Strings in Learn Markdown records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Numbered Lists With All Ones records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using One H1 in Microsoft Learn Markdown records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Reference-Style Links in Microsoft Learn records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Relative Paths for Microsoft Learn Conceptual Images records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Relative Paths in Code Snippet References records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Using Relative Paths in Learn Include Directives records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Secure External Links in Microsoft Learn records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Selectors From Include Files records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Single Selectors in Learn Markdown records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Site-Relative Links for Microsoft Learn Articles records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Standard Conceptual Images in Microsoft Learn records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Subscript and Superscript Only for Technical Accuracy records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Using Triple-Colon Syntax for Referenced Code Snippets records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal grammar rule.
Using XRef Links for Microsoft Learn API References records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
Modern technical style often uses lowercase “web,” but this is an editorial convention rather than a universal trademark rule. Microsoft explicitly lowercases web as a modifier, lowercases www in addresses, and preserves different capitalization when a product, UI label, or feature name requires it.
Writing Self-Contained Include Files records a distinct Microsoft Learn authoring convention and keeps it scoped to that documentation environment rather than presenting it as a universal writing rule.
