# 1562 Documentation Styling F4c739c3 > Documentation Styling Standards - Skill: `tools-only/1562-documentation-styling-f4c739c3` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/1562-documentation-styling-f4c739c3` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/1562-documentation-styling-f4c739c3/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/tools-only/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: ```markdown > [!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 | Callout | Use For | Example | | -------------- | ------------------------------------ | ----------------------------------------------- | | `[!NOTE]` | Background info, context, FYI | "Note: This service is in preview." | | `[!TIP]` | Best practices, optimizations | "Tip: Use managed identities over keys." | | `[!IMPORTANT]` | Must-do items, critical config | "Important: Enable TLS 1.2 minimum." | | `[!WARNING]` | Security risks, reliability concerns | "Warning: Public endpoint exposed." | | `[!CAUTION]` | Data loss risk, irreversible actions | "Caution: Purge protection cannot be disabled." | --- ## Status Indicators (Emoji) Use consistent emoji for status indication: | Purpose | Emoji | Usage Example | | ----------------- | ----- | ---------------------------------- | | Success/Complete | ✅ | `✅ Health check passed` | | Warning/Attention | ⚠️ | `⚠️ Requires manual configuration` | | Error/Critical | ❌ | `❌ Validation failed` | | Info/Tip | 💡 | `💡 Consider using Premium tier` | | Security | 🔐 | `🔐 Requires Key Vault access` | | Cost | 💰 | `💰 Estimated: $50/month` | | Reference/Link | 📚 | `📚 See: Microsoft Learn` | | Time/Schedule | ⏰ | `⏰ Runs daily at 02:00 UTC` | | Pending | ⏳ | `⏳ Awaiting approval` | --- ## Category Icons Use consistent icons for resource categories: | Category | Icon | Example | | ---------- | ---- | ----------------------------- | | Compute | 💻 | `### 💻 Compute Resources` | | Data | 💾 | `### 💾 Data Services` | | Networking | 🌐 | `### 🌐 Networking Resources` | | Messaging | 📨 | `### 📨 Messaging Resources` | | Security | 🔐 | `### 🔐 Security Resources` | | Monitoring | 📊 | `### 📊 Monitoring Resources` | | Identity | 👤 | `### 👤 Identity & Access` | | Storage | 📦 | `### 📦 Storage Resources` | --- ## WAF Pillar Icons Use consistent icons for Well-Architected Framework pillars: | Pillar | Icon | Usage | | ---------------------- | ---- | ------------------------------- | | Security | 🔒 | `### 🔒 Security Assessment` | | Reliability | 🔄 | `### 🔄 Reliability Assessment` | | Performance Efficiency | ⚡ | `### ⚡ Performance Assessment` | | Cost Optimization | 💰 | `### 💰 Cost Assessment` | | Operational Excellence | 🔧 | `### 🔧 Operational Excellence` | --- ## Collapsible Sections Use HTML `
` tags for lengthy content that doesn't need to be visible by default: ```markdown
📋 Detailed Resource Configuration | Resource | Setting | Value | | --------- | -------- | ------ | | Resource1 | Setting1 | Value1 | | Resource1 | Setting2 | Value2 |
``` ### 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 ````markdown
🔧 PowerShell Script ```powershell # Script content here ``` ````
📊 Full Resource Inventory (15 resources) | Name | Type | SKU | | ---- | ---- | --- | | ... | ... | ... |
📈 KQL Query: Error Analysis ```kusto // Query content ```
``` --- ## References Section Every documentation artifact SHOULD include a `## References` section at the bottom with relevant Microsoft Learn links. ### Standard Format ```markdown --- ## 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 | Topic | URL | | -------------------------------- | ----------------------------------------------------------------------------------- | | WAF Overview | https://learn.microsoft.com/azure/well-architected/ | | Reliability Checklist | https://learn.microsoft.com/azure/well-architected/reliability/checklist | | Security Checklist | https://learn.microsoft.com/azure/well-architected/security/checklist | | Cost Optimization Checklist | https://learn.microsoft.com/azure/well-architected/cost-optimization/checklist | | Operational Excellence Checklist | https://learn.microsoft.com/azure/well-architected/operational-excellence/checklist | | Performance Efficiency Checklist | https://learn.microsoft.com/azure/well-architected/performance-efficiency/checklist | #### Backup & Disaster Recovery | Topic | URL | | ---------------------- | -------------------------------------------------------------------------------- | | Azure Backup Overview | https://learn.microsoft.com/azure/backup/backup-overview | | Backup Best Practices | https://learn.microsoft.com/azure/backup/backup-best-practices | | RTO/RPO Metrics | https://learn.microsoft.com/azure/well-architected/reliability/metrics | | Site Recovery Overview | https://learn.microsoft.com/azure/site-recovery/site-recovery-overview | | Business Continuity | https://learn.microsoft.com/azure/well-architected/reliability/disaster-recovery | #### Security & Compliance | Topic | URL | | ---------------------------------- | -------------------------------------------------------------------------------------- | | Microsoft Cloud Security Benchmark | https://learn.microsoft.com/security/benchmark/azure/overview | | Azure Policy | https://learn.microsoft.com/azure/governance/policy/overview | | Managed Identities | https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview | | Key Vault Best Practices | https://learn.microsoft.com/azure/key-vault/general/best-practices | | Network Security Best Practices | https://learn.microsoft.com/azure/security/fundamentals/network-best-practices | #### Monitoring & Operations | Topic | URL | | ----------------------- | --------------------------------------------------------------------------- | | Azure Monitor Overview | https://learn.microsoft.com/azure/azure-monitor/overview | | Log Analytics | https://learn.microsoft.com/azure/azure-monitor/logs/log-analytics-overview | | Alerting Best Practices | https://learn.microsoft.com/azure/azure-monitor/best-practices-alerts | | Application Insights | https://learn.microsoft.com/azure/azure-monitor/app/app-insights-overview | #### Cost Management | Topic | URL | | ------------------------ | ------------------------------------------------------------------------------------------------------ | | Cost Management Overview | https://learn.microsoft.com/azure/cost-management-billing/costs/overview-cost-management | | Azure Pricing Calculator | https://azure.microsoft.com/pricing/calculator/ | | Reserved Instances | https://learn.microsoft.com/azure/cost-management-billing/reservations/save-compute-costs-reservations | --- ## Example: Enhanced Section ### Before (Plain) ```markdown ## Backup Strategy | Resource | Backup Method | Retention | | -------- | ------------- | --------- | | SQL DB | Automated | 7 days | ``` ### After (Enhanced) ````markdown ## 💾 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.
📚 Backup Configuration Commands ```bash # Enable geo-redundant backup az sql db update --resource-group rg-prod --server sql-prod --name db-main --backup-storage-redundancy Geo ``` ````
--- ## References | Topic | Link | | --------------------------- | ------------------------------------------------------------------------------------------------------- | | Azure Backup Best Practices | [Microsoft Learn](https://learn.microsoft.com/azure/backup/backup-best-practices) | | Geo-Redundant Backup | [Documentation](https://learn.microsoft.com/azure/backup/backup-create-rs-vault#set-storage-redundancy) | ``` --- _Last updated: February 2025_ ```