drawio-mcp: Instructions file for GitHub Copilot

Documentation Maintenance Guidelines

Purpose

This document defines mandatory rules for maintaining project documentation. As an AI assistant, you must follow these guidelines when creating, updating, or reviewing documentation to ensure consistency, completeness, and maintainability.

Core Principles

1. Documentation is Code

• Treat documentation with the same rigor as source code
• Review and update documentation in the same commit as code changes
• Documentation changes require the same quality standards as code

2. Single Source of Truth

• Each piece of information exists in exactly one place
• Use references and links instead of duplicating content
• Update linked content when the source changes

3. Progressive Disclosure

• Start with essential information, layer in complexity
• Beginners should find quick starts easily
• Experts should find detailed technical information accessible

4. Documentation-Driven Development

• Update documentation BEFORE implementing changes
• Use documentation as specification
• Keep documentation synchronized with implementation

5. Centralized Documentation Storage

• ALL project documentation MUST be stored in the /docs folder
• Code-specific documentation (like implementation notes) should be in the code directory
• Before creating new documentation, ALWAYS review the existing /docs folder structure
• Update existing documents instead of creating duplicates

6. Documentation Size and Readability

• Maximum document size: ~1000 lines for optimal readability
• If a document exceeds this limit, split it into logical sections
• Use clear naming for multi-part documents: topic-part-1.md, topic-part-2.md
• Each part should be self-contained with proper context and cross-references

Quick Reference: Documentation Workflow

Every time you need to create or update documentation:

┌─────────────────────────────────────────────────────────┐
│ STEP 1: Review Existing /docs Folder                   │
│ - Use file_search or list_dir to explore structure     │
│ - Identify existing related documents                  │
│ - Check for duplicate content                          │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│ STEP 2: Decide Update vs New                           │
│ - Update existing if content is related                │
│ - Create new only if truly distinct topic              │
│ - Check current document size before updating          │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│ STEP 3: Verify Location                                │
│ - /docs/architecture/ → Design & decisions             │
│ - /docs/guides/ → How-to & tutorials                   │
│ - /docs/api/ → API reference                           │
│ - /docs/getting-started/ → Onboarding                  │
│ - Code directory → Temporary only, plan migration      │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│ STEP 4: Check Size & Split if Needed                   │
│ - Target: < 1000 lines per document                    │
│ - If over limit: Create {topic}-part-{N}.md            │
│ - Add navigation links between parts                   │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│ STEP 5: Update & Cross-Reference                       │
│ - Write/update content                                 │
│ - Add links from related documents                     │
│ - Update CHANGELOG.md                                  │
│ - Update main README.md if needed                      │
└─────────────────────────────────────────────────────────┘