julien-ref-doc-production
Documentation production methodology with DRY principles. Covers 8 document types (GUIDE, INCIDENT, SESSION, AUDIT, RECHERCHE, etc.), naming conventions, and YAML metadata.
When & Why to Use This Skill
This Claude skill provides a comprehensive documentation production methodology based on DRY (Don't Repeat Yourself) principles. It offers standardized templates for eight distinct document types—including technical guides, incident reports, and session logs—ensuring consistency through strict naming conventions and YAML metadata integration for better maintainability and searchability.
Use Cases
- Standardizing project documentation by implementing DRY principles to reduce redundancy and improve information architecture.
- Generating structured incident reports (post-mortems) with clear sections for symptoms, timelines, root causes, and prevention strategies.
- Creating 'living' technical guides that include version control, audience targeting, and standardized YAML metadata for automated processing.
- Documenting development sessions to track specific achievements, technical decisions, and modified files for enhanced project traceability.
- Conducting technical audits or research investigations using predefined frameworks to ensure consistent reporting of findings and recommendations.
| name | julien-ref-doc-production |
|---|---|
| description | Documentation production methodology with DRY principles. Covers 8 document types (GUIDE, INCIDENT, SESSION, AUDIT, RECHERCHE, etc.), naming conventions, and YAML metadata. |
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