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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

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.
namejulien-ref-doc-production
descriptionDocumentation 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

  1. DRY: Avoid duplication, use cross-references
  2. Living docs: Update rather than create, archive obsolete
  3. Targeted audience: Humans | LLM | All + level (1-10)
  4. 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:

  1. Choose type
  2. Use template
  3. Fill all sections
  4. Name correctly
  5. Add metadata
  6. Reference in README
  7. 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

  • julien-ref-doc-review: Use after writing to annotate and review documentation with @FIX, @TODO, @VERIFY tags