607 Best Practices 5d71859d

# 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

| Level | Content Type | Example |
|-------|--------------|---------|
| Root (Level 1) | Major sections | Getting Started, API Reference |
| Level 2 | Topics within sections | Installation, Authentication |
| Level 3 | Specific details | Rarely needed |

**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

```markdown
---
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:

```markdown
### 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:**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `provider` | Yes | Authentication provider type |
| `client_id` | Yes | OAuth2 application ID |
| `redirect_uri` | Yes | Callback URL after authentication |
| `scopes` | No | Requested permissions (default: read) |

```

### 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

```markdown
| 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

```markdown
# 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:

```markdown
## 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:

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

# Current Page Title
```

## Maintenance

### Regular Review Process

| Frequency | Action |
|-----------|--------|
| Weekly | Check for broken links |
| Monthly | Review and update outdated content |
| Quarterly | Reorganize structure if needed |
| Per Release | Update version-specific documentation |

### Handling Outdated Content

**Option 1: Archive Section**

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

**Option 2: Version Tags in YAML**

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

**Option 3: Inline Notices**

```markdown
> [!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:**

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

2. **Include common search terms:**

```markdown
## Authentication (Login/Sign In)

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

3. **Create FAQ pages:**

```markdown
## 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:

```yaml
# 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

| Role | Responsibility |
|------|----------------|
| Wiki Admin | Structure, permissions, maintenance |
| Content Owner | Specific section accuracy |
| Contributors | Page updates, new content |
| Reviewers | Quality assurance |

## 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:

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

## Security

### Sensitive Information

**Never include in wiki:**

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

**Instead:**

```markdown
## 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