Azure DevOps Wiki Best Practices

Azure DevOps Wiki Best Practices

Comprehensive guide for creating and maintaining effective Azure DevOps wikis.

Planning Your Wiki

Choose the Right Wiki Type

Provisioned Wiki - Best for:

• Team-level documentation
• Quick onboarding guides
• Meeting notes and decisions
• Internal processes

Published Code Wiki - Best for:

• API documentation
• SDK references
• Product documentation requiring versioning
• Documentation that lives alongside code
• Multiple documentation sets per project

Information Architecture

Before creating pages, plan your structure:

Wiki Root
├── Home (Welcome + navigation)
├── Getting Started/
│   ├── Prerequisites
│   ├── Installation
│   ├── Quick Start
│   └── First Steps
├── User Guide/
│   ├── Core Concepts
│   ├── Common Tasks
│   └── Advanced Usage
├── API Reference/
│   ├── Overview
│   ├── Authentication
│   └── Endpoints
├── Troubleshooting/
│   ├── Common Issues
│   └── FAQ
└── Contributing

Page Organization

Hierarchy Best Practices

Recommendation: Keep hierarchy to 2-3 levels maximum. Deep nesting makes navigation difficult.

Page Naming Conventions

Do:

getting-started.md
api-authentication.md
troubleshooting-errors.md
deployment-guide-v2.md

Don't:

Getting Started.md          # Spaces cause URL issues
API_Authentication.md       # Underscores less readable
TROUBLESHOOTING-ERRORS.md   # All caps harder to read
deployment guide v2.md      # Multiple spaces problematic

The .order File Strategy

Organize pages logically, not alphabetically:

# Root .order - most important first
Home
Getting-Started
User-Guide
API-Reference
Troubleshooting
Contributing
Release-Notes

For large sections, group related content:

# API-Reference/.order
Overview
Authentication
Core-Endpoints
Webhooks
Error-Codes
Rate-Limits

Content Best Practices

Page Structure Template

---
title: Page Title
author: Author/Team
updated: 2024-01-15
tags:
  - category
  - topic
---

[[_TOC_]]

## Overview

Brief description of what this page covers and who it's for.

## Prerequisites

What the reader needs before starting.

## Main Content

### Section 1

Content with examples...

### Section 2

More content...

## Next Steps

- [Related Page 1](./related-page-1)
- [Related Page 2](./related-page-2)

## See Also

- External references
- Related documentation

Writing Guidelines

Be Concise:

• Use bullet points for lists
• Keep paragraphs short (3-4 sentences)
• Use tables for structured data

Be Complete:

• Include prerequisites
• Provide examples
• Add troubleshooting sections

Be Discoverable:

• Use descriptive headings
• Add YAML metadata with tags
• Cross-link related pages
• Include keywords users might search for

Code Examples

Always include context and explanation:

### Configure Authentication

Set up OAuth2 authentication by adding the following to your `config.yaml`:

```yaml
auth:
  provider: oauth2
  client_id: ${CLIENT_ID}
  redirect_uri: https://app.example.com/callback
  scopes:
    - read
    - write

Parameters:

### Visual Content

**Use Mermaid for:**
- Architecture diagrams
- Process flows
- Sequence diagrams
- Decision trees

```markdown
::: mermaid
sequenceDiagram
    participant User
    participant API
    participant Database

    User->>API: POST /login
    API->>Database: Validate credentials
    Database-->>API: User data
    API-->>User: JWT token
:::

Use images for:

• Screenshots
• UI mockups
• Complex diagrams (export from tools like Excalidraw)

Tables for Structured Data

| Feature | Free Tier | Pro Tier | Enterprise |
|---------|-----------|----------|------------|
| Users | 5 | 50 | Unlimited |
| Storage | 1 GB | 10 GB | 100 GB |
| Support | Community | Email | Dedicated |
| SLA | None | 99.9% | 99.99% |

Navigation & Linking

Internal Links

# Same folder
[Related Page](./related-page)

# Subfolder
[Child Page](./folder/child-page)

# Parent folder
[Parent Page](../parent-page)

# Absolute from wiki root
[Home Page](/Home)

# Link to heading
[Specific Section](./page#section-heading)

Cross-Referencing

Create a network of related content:

## Related Topics

- **Getting Started**: [Quick Start Guide](../getting-started/quick-start)
- **Deep Dive**: [Advanced Configuration](./advanced-configuration)
- **Troubleshooting**: [Common Errors](../troubleshooting/common-errors)

Breadcrumbs Pattern

For deep pages, add manual breadcrumbs:

[Home](/) > [User Guide](/user-guide) > [Advanced](/user-guide/advanced) > Current Page

# Current Page Title

Maintenance

Regular Review Process

Handling Outdated Content

Option 1: Archive Section

Wiki Root
└── Archive/
    ├── v1-documentation
    └── deprecated-features

Option 2: Version Tags in YAML

---
title: Feature X
status: deprecated
deprecated_since: 2024-01-01
replacement: /features/feature-y
---

Option 3: Inline Notices

> [!WARNING]
> This feature is deprecated as of v2.0. See [Feature Y](./feature-y) for the replacement.

Search Optimization

Make content findable:

1. Use YAML metadata:

---
tags:
  - authentication
  - oauth2
  - security
  - login
keywords: sign in, log in, access token, bearer token
---

2. Include common search terms:

## Authentication (Login/Sign In)

This guide covers user authentication, including:
- OAuth2 login flow
- API key authentication
- Token-based access

3. Create FAQ pages:

## Frequently Asked Questions

### How do I reset my password?
...

### Why can't I access the API?
...

Collaboration

Branch Policies for Code Wikis

For published code wikis, consider branch policies:

# azure-pipelines.yml for wiki validation
trigger:
  branches:
    include:
      - main
  paths:
    include:
      - docs/**

pool:
  vmImage: ubuntu-latest

steps:
  - script: |
      # Check for broken internal links
      npm install -g markdown-link-check
      find docs -name "*.md" -exec markdown-link-check {} \;
    displayName: 'Validate links'

Review Process

1. Create feature branch for major changes
2. Submit PR with documentation changes
3. Review for accuracy and clarity
4. Merge to main/wikiMain

Ownership Model

Performance

Optimize Large Wikis

• Keep individual page size under 18 MB
• Use .attachments/ folder for images
• Compress images before uploading
• Split very long pages into multiple pages

Attachment Management

.attachments/
├── diagrams/
│   ├── architecture-v1.png
│   └── architecture-v2.png
├── screenshots/
│   ├── login-screen.png
│   └── dashboard.png
└── downloads/
    └── sample-config.yaml

Reference in pages:

![Architecture](/.attachments/diagrams/architecture-v2.png)

Security

Sensitive Information

Never include in wiki:

• API keys or secrets
• Passwords
• Connection strings
• Personal data

Instead:

## Configuration

Set the following environment variables:

| Variable | Description |
|----------|-------------|
| `API_KEY` | Your API key from the portal |
| `DATABASE_URL` | Connection string from Azure |

Get your credentials from [Azure Portal](https://portal.azure.com).

Access Control

• Wiki inherits project permissions
• Contributors can edit
• Readers can view
• Consider separate wikis for sensitive internal docs