VARIABLES USED: - [TOOLS_STACK]: Notion + GitHub + Slack + Linear + Google Drive - [PAIN_POINTS]: inconsistent versioning, slow approval cycles, scattered runbooks, no API source of truth, outdated sales decks - [AUDIENCES]: Engineering, Sales, Executive Leadership - [ORG_SIZE]: Series B SaaS, 180 employees, 6 time zones, preparing SOC 2 Type II audit - [PRIMARY_GOAL]: Cut onboarding 4w→1w + pass SOC 2 audit ═══════════════════════════════════════════════════════════════ 📁 1. FOLDER ARCHITECTURE Naming: snake_case folders, kebab-case-vX.Y.md files, .mmd for diagrams, .json for metadata, .yaml (OpenAPI) for public APIs. documentation_hub/ ├── engineering/ │ ├── product_docs/{api_reference, technical_specs, architecture_diagrams}/ │ │ ├── public-api-v2.3.yaml │ │ ├── customer-segmentation-engine-v1.0.md │ │ └── event-driven-platform-v1.2.mmd │ ├── operations/{runbooks, sop, incident_reviews}/ → database-failover-runbook-v1.0.md │ └── onboarding/{learning_paths, system_overviews}/ → backend-engineer-path-v1.0.md ├── sales/ │ ├── product_positioning/{one_pagers, battlecards}/ → enterprise-security-one-pager-v2.0.md │ ├── roadmap_alignment/{release_summaries, feature_status}/ → q3-release-summary-v1.0.md │ └── customer_enablement/{demos, faq}/ → enterprise-demo-script-v1.0.md ├── leadership/ │ ├── strategy/{executive_memos, decision_records}/ → platform-modernization-memo-v1.0.md │ ├── compliance/{soc2_controls, audit_evidence}/ → cc6-access-control-v1.0.md │ └── board_reporting/{quarterly_reviews, kpi_reports}/ → board-review-q3-v1.0.md └── shared/{templates, metadata, archive}/ 📋 2. FIVE READY-TO-USE TEMPLATES (each as Markdown with YAML frontmatter) A. Technical Specification (document_id, type=technical_specification, audience=[Engineering], sla=48h, tags=[engineering/specification]): # Overview / Problem Statement / Goals / Non-Goals → # Requirements (Functional + NFR tables) → # Architecture (Components, Data Flow) → # Risks (Impact + Mitigation) → # Rollout Plan → # Success Metrics → # Related Documents B. Sales One-Pager (type=sales_one_pager, sla=24h): # Customer Problem | # Solution | # Key Benefits | # Competitive Differentiators (table) | # Product Roadmap Alignment (Feature/Status/Release) | # Customer Proof | # Approved Messaging C. Executive Memo (type=executive_memo, sla=24h): # Decision Required: [YES/NO] | # Requested Decision | # Executive Summary | # Business Impact | # Risks (table) | # Recommendation | # Changelog | # Related Documents D. SOP (type=sop): # Purpose | # Prerequisites | # Procedure (Step/Owner/Action) | # Validation | # Failure Modes | # Escalation Path E. Meeting Pre-Read Brief (type=meeting_pre_read, sla=12h): # TL;DR | # Decisions Required (Decision/Owner/Deadline) | # Context | # Options (Pros/Cons) | # Pre-Read Links | # Recommendation 🗂️ 3. METADATA SCHEMA (JSON) { "document_id": "ENG-SPEC-0042", "title": "Customer Segmentation Engine", "type": "technical_specification", "audience": ["Engineering"], "owner": "jane.smith", "reviewers": ["cto", "platform_lead", "security_lead"], "tags": ["engineering", "technical_specification", "customer_data"], "version": "1.2", "created_date": "2026-05-22", "last_modified": "2026-05-24", "expiry_date": "2026-11-22", "sla_approval_hours": 48, "related_docs": ["ADR-021", "API-003", "RUNBOOK-018"], "status": "approved", "criticality": "high", "source_system": "Notion", "github_repo": "platform-docs", "approval_record": "LIN-4218", "soc2_control_mapping": ["CC6.1", "CC7.2"] } 🏷️ 4. THREE-LEVEL TAGGING TAXONOMY engineering → technical_specification → api → engineering/specification/api engineering → runbook → incident_response → engineering/runbook/incident_response engineering → onboarding → backend → engineering/onboarding/backend sales → one_pager → security → sales/one_pager/security sales → battlecard → competition → sales/battlecard/competition leadership → executive_memo → strategy → leadership/executive_memo/strategy leadership → audit_evidence → soc2 → leadership/audit/soc2 leadership → decision_record → governance → leadership/decision_record/governance ⚙️ 5. APPROVAL WORKFLOW graph TD A[Document Created] --> B{Audience?} B -->|Engineering| C[Tech Lead Review – SLA 48h] B -->|Sales| D[Sales Manager Review – SLA 24h] B -->|Executive| E[C-Suite Review – SLA 24h] C --> F{Approved?} D --> F E --> F F -->|Yes| G[Publish + Notify Stakeholders] F -->|No| H[Auto-Reassign + Feedback] Escalation auto-trigger at +50% of SLA → notify manager + Documentation Lead. SLA Matrix: Eng 24/48/72h, Sales 12/24/48h, Exec 12/24/48h. ✍️ 6. STYLE GUIDE Engineering Voice: precise, implementation-focused. Sales Voice: customer outcome first. Executive Voice: decision-oriented, financial impact first. H1=title only, H2=sections, H3=subsections, H4=exceptions. Bullets ≥3 items. Prose for summaries ≤150 words. Mermaid only. Forbidden: unversioned screenshots, "TBD" >14 days, Slack links as record, duplicate-scope docs. ✅ 7. GOOD-vs-GREAT QUALITY CHECKLIST | Criterion | Good | Great | | Metadata complete? | Required fields | Required + optional | | Version specified? | Yes | Semantic versioning | | Owner assigned? | One owner | Owner + delegate | | Reviewers assigned? | ≥1 | Cross-functional | | Expiry date present? | Yes | Auto-renew attached | | Related docs linked? | ≥1 | Full dependency graph | | Success metrics defined? | Present | Quantified target | | Decision record included? | Referenced | Traceable to approval ticket | | SOC2 mapping present? | Mapped | Evidence attached | | Search tags applied? | 3 tags | 5+ taxonomy-compliant | 🚚 8. LEGACY MIGRATION PLAN (14 days total) 1. Inventory Notion/Drive/Slack docs — Documentation Lead — inventory_scan.py — 95% cataloged — 2d 2. Extract Slack runbooks — Platform Engineer — Slack Export API + slack_runbook_extractor.py — 100% moved — 2d 3. Create metadata records — Documentation Lead — metadata_generator.py — 100% tagged — 3d 4. Sync API docs into GitHub — Staff Engineer — GitHub REST API + OpenAPI Generator — 1 source — 3d 5. Approval & publication — Engineering Manager — Linear API + Notion API workflow — 100% approved — 4d 🔌 9. INTEGRATION CONNECTORS Central hub: GitHub Docs Repository ↕ Notion ↕ (Slack, Linear, Google Drive) Notion → Notion API /v1/pages, /v1/databases | GitHub → REST API v3 + GraphQL | Slack → Conversations + Events API | Linear → GraphQL API | Drive → Drive API v3 | Catalog → document-catalog.json in GitHub Bidirectional sync: GitHub↔Notion 15min, Linear→Notion 30min, Slack runbooks→Notion hourly, Drive→GitHub Archive daily. 📊 10. SUCCESS METRICS | Component | KPI | Target | Goal | | Folder Architecture | Docs in approved location | 95% | SOC2 | | Templates | New docs using templates | 100% | Audit Trail | | Metadata Schema | Complete metadata | 98% | SOC2 | | Tagging Taxonomy | Search success | >90% | Onboarding | | Approval Workflow | Median approval time | <48h | Faster decisions | | Style Guide | QA compliance | >95% | Consistency | | Quality Checklist | Docs passing first review | >90% | SOC2 | | Migration Plan | Legacy docs migrated | 100% | Single Source | | Connectors | Sync failures/month | <2 | Reliability | | Engineering Onboarding | Time-to-productivity | 4w → 1w | PRIMARY OUTCOME | | Runbook Consolidation | Slack runbooks remaining | 0 | Ops Readiness | | API Docs | Public API source count | Exactly 1 | Single Source | | Sales Content Freshness | Roadmap-linked current | >95% | Revenue Enablement | | SOC2 Evidence | Controls with evidence | 100% | Audit Pass Rate |