majiayu000 Documentation Production Methodology
Version: 2.0.0-DRY
Principles
- DRY: Avoid duplication, use cross-references
- Living docs: Update rather than create, archive obsolete
- Targeted audience: Humans | LLM | All + level (1-10)
- Actionable: Concrete examples, reproducible commands
Structure
project/
├── docs/
│ ├── guides/ # Evolving docs
│ └── rapports/ # Event-based docs
└── README.md # Index
Naming Conventions
EVOLVING Docs (living docs)
Types: GUIDE, METHODOLOGIE, AUDIT, TROUBLESHOOTING
Name: [TYPE]_[subject].md (no date)
Timestamp: In content, per section
Required YAML header:
---
title: "Guide X"
version: X.Y.Z
created: YYYY-MM-DD
updated: YYYY-MM-DD
authors: [...]
audience: ["Humans"|"LLM"|"All"]
level: "Beginner (1-3)" | "Intermediate (4-6)" | "Expert (7-10)"
status: "Active" | "Archived" | "Draft"
tags: [...]
related: [related files]
---
EVENT-BASED Docs (snapshots)
Types: INCIDENT, SESSION, RECHERCHE, RECOMMANDATIONS, MIGRATION, PERFORMANCE, SECURITE
Name: YYYY.MM.DD_HH.mm_[commit-short]_[TYPE]_[subject].md
Timestamp format: 2025.10.14_12.33 (dots + underscores)
Required metadata:
## Metadata
- **Date**: YYYY-MM-DD HH:MM
- **Commit**: abc1234 (7 chars)
- **Duration**: X hours (if applicable)
Document Types
INCIDENT (event-based)
When: Blocking problem resolved
# Incident: [Title]
## Metadata
- Date, Duration, Severity, Commit
## Summary
[2-3 sentences]
## Symptoms → Timeline → Cause → Solution → Prevention
## References
SESSION (event-based)
When: Significant session (feature, refactor)
# Session: [Title]
## Metadata
- Date, Duration, Commits
## Objective → Achievements → Decisions → Problems → Modified files → Tests → Next
## References
GUIDE (evolving)
When: Reusable procedure
---
[Complete YAML header]
---
# Guide: [Title]
## Overview → Concepts → Step-by-step → Troubleshooting → Examples → References
AUDIT (evolving or event-based)
When: Pre-intervention analysis
# Audit: [Title]
## Metadata
## Executive Summary
- Score, Risks, Recommendations
## Findings (Critical, Major, Minor)
## Prioritized recommendations → Action plan → References
RECHERCHE (event-based)
When: Investigation, exploration, benchmark
# Research: [Title]
## Metadata
- Date, Objective, Duration
## Question → Methodology → Discoveries → Options → Comparison → Recommendation → References
RECOMMANDATIONS (event-based)
When: Important technical decision
# Recommendations: [Title]
## Metadata
## Context → Evaluated options (Pros/Cons/Evaluation) → Decision matrix → Recommendation → Risks → Next
MIGRATION (event-based)
When: Tech/version/infra migration
# Migration: [Title]
## Metadata
## Objective → Before/After → Procedure → Verifications → Problems → Rollback plan → Lessons → Follow-up
PERFORMANCE (event-based)
When: Measurable optimization
# Performance: [Title]
## Metadata
## Summary → Metrics before → Optimizations → Metrics after → Charts → Recommendations → References
SECURITE (event-based)
When: Security audit, vulnerabilities
# Security Audit: [Title]
## Metadata
## Summary → Vulnerabilities (Critical/Major/Minor) → Best practices → Remediation plan → Verifications → References
Workflow
Create report when:
- Session > 1h with significant changes → SESSION
- Blocking problem resolved → INCIDENT
- Investigation completed → RECHERCHE
- Technical decision → RECOMMANDATIONS
- New procedure → GUIDE (or update)
- Migration completed → MIGRATION
- Measurable optimization → PERFORMANCE
- Vulnerability found → SECURITE
Production:
- Choose type
- Use template
- Fill all sections
- Name correctly
- Add metadata
- Reference in README
- Commit
Quality Checklist
Content
- All sections filled
- No TODO/To complete
- Commands tested
- Paths correct
- Links valid
Form
- Naming respected
- Metadata present
- Valid Markdown
- Code blocks with language
Context
- Audience identified
- Level adapted
- Cross-references
Traceability
- Commits mentioned
- Files listed
- Timeline clear
Related Skills
- julien-ref-doc-review: Use after writing to annotate and review documentation with @FIX, @TODO, @VERIFY tags