Documentation Production Methodology

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

---

Related Skills

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