1562 Documentation Styling F4c739c3

Documentation Styling Standards

This file defines the visual styling standards for all agent-generated documentation. Agents and skills MUST reference these standards when generating artifacts.

Callout Styles

Use GitHub-flavored markdown callouts for emphasis:

> [!NOTE]
> Informational callout for tips and supplementary context.

> [!TIP]
> Best practice recommendation or optimization suggestion.

> [!IMPORTANT]
> Critical configuration or requirement that must not be overlooked.

> [!WARNING]
> Security concern, reliability risk, or potential issue.

> [!CAUTION]
> Potential data loss, breaking change, or irreversible action.

When to Use Each Callout

Status Indicators (Emoji)

Use consistent emoji for status indication:

Category Icons

Use consistent icons for resource categories:

WAF Pillar Icons

Use consistent icons for Well-Architected Framework pillars:

Collapsible Sections

Use HTML <details> tags for lengthy content that doesn't need to be visible by default:

<details>
<summary>📋 Detailed Resource Configuration</summary>

| Resource  | Setting  | Value  |
| --------- | -------- | ------ |
| Resource1 | Setting1 | Value1 |
| Resource1 | Setting2 | Value2 |

</details>

When to Use Collapsible Sections

• Long tables (>10 rows)
• Detailed configuration that's reference material
• Code examples that support but aren't central to the narrative
• Historical data or change logs
• Appendix content

Collapsible Section Patterns

<!-- For code blocks -->
<details>
<summary>🔧 PowerShell Script</summary>

```powershell
# Script content here
```

// Query content

References Section

Every documentation artifact SHOULD include a ## References section at the bottom with relevant Microsoft Learn links.

Standard Format

---

## References

> [!NOTE]
> 📚 The following Microsoft Learn resources provide additional guidance.

| Topic                       | Link                                                                       |
| --------------------------- | -------------------------------------------------------------------------- |
| Well-Architected Framework  | [Overview](https://learn.microsoft.com/azure/well-architected/)            |
| Azure Backup Best Practices | [Guidance](https://learn.microsoft.com/azure/backup/backup-best-practices) |

Reference Links by Topic

Well-Architected Framework

Backup & Disaster Recovery

Security & Compliance

Monitoring & Operations

Cost Management

Example: Enhanced Section

Before (Plain)

## Backup Strategy

| Resource | Backup Method | Retention |
| -------- | ------------- | --------- |
| SQL DB   | Automated     | 7 days    |

After (Enhanced)

## 💾 Backup Strategy

> [!IMPORTANT]
> Backup configurations must align with business RTO/RPO requirements.

| Resource   | Backup Method  | Retention | RTO | RPO | Status        |
| ---------- | -------------- | --------- | --- | --- | ------------- |
| ✅ SQL DB  | Automated PITR | 7 days    | 4h  | 1h  | Configured    |
| ⚠️ Storage | Manual export  | 30 days   | 24h | 24h | Review needed |

> [!TIP]
> 💡 Consider enabling geo-redundant backup for production workloads.

<details>
<summary>📚 Backup Configuration Commands</summary>

```bash
# Enable geo-redundant backup
az sql db update --resource-group rg-prod --server sql-prod --name db-main --backup-storage-redundancy Geo
```

References

---

_Last updated: February 2025_