Écrire la documentation

Progression d’apprentissage0 / 404

0 / 24 validations dans ce chapitre

Réinitialiser la progression

Construire README, USER_DOC et DEV_DOC depuis les commandes réelles.

Dans ce chapitre : 4 étapes et 24 preuves de validation.

Étape 104 — Écrire Description et Instructions

Objectif. Tu transformeras le démarrage du projet en procédure reproductible.

État du projet avant cette étape. La stack et ses audits sont terminés. La documentation doit maintenant décrire ce qui existe réellement, sans commandes inventées.

Comprendre le changement

Le README commence par la phrase imposée, résume le projet, décrit l’architecture puis donne les prérequis, la configuration et les commandes de lancement.

Exigence du sujet · p. 11

README.md doit être en anglais, commencer par la phrase prescrite et contenir Description et Instructions.

Faire une seule chose

Rédige en anglais la première moitié du README et teste chaque instruction dans une VM propre ou depuis un état arrêté.

Fichiers ou emplacements concernés

• README.md

À ÉCRIRE DANS📄 README.md · squelette en anglais

Copier

Avant de copier : remplacez <login><Goal and brief overview.><Architecture, Docker usage, included sources and main design choices.><Prerequisites, local configuration, secret creation, build, start and access.> par vos valeurs.

*This activity has been created as part of the 42 curriculum by <login>.*

# Inception

## Description
<Goal and brief overview.>

### Project description
<Architecture, Docker usage, included sources and main design choices.>

## Instructions
<Prerequisites, local configuration, secret creation, build, start and access.>

Ce que fait chaque partie

1. Première ligne : italique Markdown et formulation imposée.
2. Description : objectif et aperçu plus choix techniques.
3. Instructions : tout ce qui permet compilation/installation/exécution.

Résultat attendu

Un lecteur neuf sait ce que construit le projet et comment lancer make.

Si cela échoue

Ne placez aucun vrai mot de passe dans un exemple. Utilisez <placeholder> ou des valeurs explicitement fictives.

À ÉCRIRE DANS📄 README.md · sections obligatoires

Copier

Avant de copier : remplacez <Official Docker documentation page used><NGINX / MariaDB / PHP / WordPress reference used><Tasks assisted, files or topics concerned, and how outputs were reviewed and tested.> par vos valeurs.

## Design choices and comparisons
### Virtual Machines vs Docker
### Secrets vs Environment Variables
### Docker Network vs Host Network
### Docker Volumes vs Bind Mounts

## Resources
- <Official Docker documentation page used>
- <NGINX / MariaDB / PHP / WordPress reference used>

### AI usage
<Tasks assisted, files or topics concerned, and how outputs were reviewed and tested.>

Ce que fait chaque partie

1. Quatre titres : rendent les comparaisons faciles à vérifier.
2. Resources : liens réellement consultés, pas une liste décorative.
3. AI usage : tâches et parties précises, conformément au sujet.

Résultat attendu

Les quatre comparaisons et une déclaration IA factuelle sont présentes.

Si cela échoue

Une phrase générique AI was used n’est pas assez précise. Indiquez où, pour quoi et comment chaque sortie a été validée.

Prouver que c’est correct

Preuves de validation 0 / 5

Une case correspond à une preuve observée ou expliquée, pas simplement à une commande copiée.

La toute première ligne est en italique et reprend exactement la phrase demandée par le PDF.Le README est écrit en anglais.Description explique l’objectif, Docker, les sources incluses et l’architecture réelle.Instructions liste prérequis, configuration et exécution.Toutes les commandes documentées ont été testées.

Question de soutenance — Quel document est explicitement imposé en anglais ?

README.md. Le PDF n’impose pas explicitement la langue des deux autres guides.

Étape 105 — Compléter Resources, IA et comparaisons

Objectif. Tu documenteras tes choix au lieu de réciter des définitions.

État du projet avant cette étape. Le lecteur sait déjà lancer le projet. Il doit aussi connaître les sources, l’éventuelle utilisation de l’IA et les décisions techniques.

Comprendre le changement

Les comparaisons demandées servent à expliquer pourquoi cette architecture existe : VM/container, secret/env, réseau Docker/host, volume/bind mount. Chaque comparaison doit relier différence, avantage, limite et choix du projet.

Exigence du sujet · p. 11

Le README doit contenir Resources, la description de l’usage de l’IA et les comparaisons demandées par le sujet.

Faire une seule chose

Ajoute Resources, AI usage et les quatre comparaisons. Cite des ressources réellement consultées et vérifie les liens.

Fichiers ou emplacements concernés

• README.md

À EXÉCUTER DANS🖥️ Dans la VM · 📁 racine du repository

Copier

head -n 1 README.md
grep -nE '^## (Description|Instructions|Resources)' README.md
grep -nE '^### (Virtual Machines vs Docker|Secrets vs Environment Variables|Docker Network vs Host Network|Docker Volumes vs Bind Mounts)' README.md

Ce que fait chaque partie

1. head : contrôle la première ligne exacte.
2. grep titres : confirme les sections vérifiables.

Résultat attendu

Tous les titres apparaissent et la première ligne est le texte italique attendu.

Si cela échoue

Ces commandes valident la présence, pas la qualité. Relisez en anglais et exécutez réellement Instructions.

Prouver que c’est correct

Preuves de validation 0 / 7

Une case correspond à une preuve observée ou expliquée, pas simplement à une commande copiée.

Resources contient des liens ou références réellement utilisés.L’usage de l’IA est déclaré honnêtement, y compris les parties concernées.VM et container sont comparés.Docker secret et variable d’environnement sont comparés.Réseau Docker et host network sont comparés.Docker volume et bind mount sont comparés.Chaque comparaison explique le choix effectué dans ce projet.

Question de soutenance — Quel document est explicitement imposé en anglais ?

README.md. Le PDF n’impose pas explicitement la langue des deux autres guides.

Étape 106 — Écrire le guide utilisateur

Objectif. Tu expliqueras l’usage quotidien sans demander de connaissances Docker.

État du projet avant cette étape. README.md explique le projet aux développeurs. USER_DOC.md s’adresse à la personne qui veut simplement utiliser le site.

Comprendre le changement

Le guide utilisateur présente les services, le démarrage et l’arrêt, l’accès au site et à l’administration, la gestion des identifiants et le contrôle de l’état.

Exigence du sujet · p. 12

USER_DOC.md doit expliquer les services fournis, le lancement et l’arrêt, l’accès au site et à l’administration, les credentials et la vérification des services.

Faire une seule chose

Rédige USER_DOC.md en Markdown avec des procédures courtes et testables. Le PDF n’impose pas explicitement sa langue ; choisis une langue cohérente et claire. N’y copie aucun vrai secret.

Fichiers ou emplacements concernés

• USER_DOC.md

À ÉCRIRE DANS📄 USER_DOC.md · première moitié

Copier

# User documentation
## Services provided
## Start and stop the stack
## Access the website
## Access the administration panel

Ce que fait chaque partie

1. Services : rôle visible des trois composants.
2. Start/stop : commandes, emplacement et résultat.
3. Access : domaine HTTPS et avertissement éventuel du certificat local.
4. Administration : https://<login>.42.fr/wp-admin.

Résultat attendu

Un administrateur sait démarrer, arrêter et atteindre les deux interfaces.

Si cela échoue

Ne supposez pas que le lecteur connaît le dossier courant : indiquez la racine du repository et la VM.

À ÉCRIRE DANS📄 USER_DOC.md · seconde moitié

Copier

Avant de copier : remplacez <login> par vos valeurs.

## Credentials
- Location and filenames (never real values)
- Required permissions
- Rotation procedure
- Git safety warning

## Check service health
- make ps
- make logs
- curl -kI https://<login>.42.fr

Ce que fait chaque partie

1. Credentials : localisation et gestion, aucune valeur.
2. Health : état Compose, logs et test utilisateur.

Résultat attendu

L’utilisateur sait diagnostiquer sans ouvrir les Dockerfiles.

Si cela échoue

Une rotation de mot de passe de base doit mettre à jour la base elle-même, pas seulement le fichier secret. Documentez la procédure réellement testée.

Prouver que c’est correct

Preuves de validation 0 / 6

Une case correspond à une preuve observée ou expliquée, pas simplement à une commande copiée.

USER_DOC.md est un fichier Markdown à la racine.Les services fournis par la stack sont présentés.Un utilisateur sait démarrer et arrêter la stack.Les URL du site et de wp-admin sont données.La procédure de gestion des credentials n’expose aucune valeur.La vérification de l’état des services est expliquée.

Question de soutenance — Quel document est explicitement imposé en anglais ?

README.md. Le PDF n’impose pas explicitement la langue des deux autres guides.

Étape 107 — Écrire le guide développeur

Objectif. Tu rendras l’infrastructure compréhensible et maintenable.

État du projet avant cette étape. L’utilisation quotidienne est documentée. DEV_DOC.md doit expliquer comment l’infrastructure est construite et modifiée.

Comprendre le changement

Le guide développeur décrit la préparation depuis zéro, la configuration et les secrets, le build et le lancement, la gestion des containers et volumes, puis le stockage et la persistance.

Exigence du sujet · p. 12

DEV_DOC.md doit couvrir la préparation depuis zéro, le build et le lancement avec Makefile et Compose, la gestion des containers et volumes, puis le stockage et la persistance.

Faire une seule chose

Rédige DEV_DOC.md en Markdown, puis suis sa procédure depuis un état propre comme si tu découvrais le repository. Le PDF n’impose pas explicitement sa langue.

Fichiers ou emplacements concernés

• DEV_DOC.md

À EXÉCUTER DANS📄 DEV_DOC.md · installation

Copier

# Developer documentation
## Prerequisites
## Repository structure
## Environment configuration
## Local secrets
## Build and launch
### With Makefile
### With Docker Compose

Ce que fait chaque partie

1. Prerequisites : VM et outils avec versions ou méthode de contrôle.
2. Configuration/secrets : fichiers à créer, placeholders sûrs.
3. Build : make comme chemin principal et Compose comme diagnostic.

Résultat attendu

Un clone neuf peut être configuré et démarré sans demander une étape cachée.

Si cela échoue

Testez la procédure sur une VM ou un environnement propre. N’introduisez pas de commande qui écrit un secret dans l’historique.

À EXÉCUTER DANS📄 DEV_DOC.md · exploitation développeur

Copier

## Container management
## Network inspection
## Volume management
## Data location and persistence
## Rebuild and reset behavior
## Troubleshooting

Ce que fait chaque partie

1. Management : commandes et effets.
2. Data : deux volumes, destinations container et chemins hôte.
3. Reset : avertissement explicite avant down --volumes ou make fclean.
4. Troubleshooting : ordre logs → inspect → réseau → permissions.

Résultat attendu

Le lecteur peut prédire si chaque commande conserve les données.

Si cela échoue

Ne décrivez pas make fclean comme un simple nettoyage si cette cible supprime les volumes.

Prouver que c’est correct

Preuves de validation 0 / 6

Une case correspond à une preuve observée ou expliquée, pas simplement à une commande copiée.

DEV_DOC.md est un fichier Markdown à la racine.Les prérequis et fichiers de configuration sont identifiés.Les commandes de build, démarrage, arrêt et logs sont expliquées.Les volumes et chemins /home/<login>/data sont décrits.Une procédure de reconstruction propre et complète existe.La procédure a été relue contre le Makefile réel.

Question de soutenance — Quel document est explicitement imposé en anglais ?

README.md. Le PDF n’impose pas explicitement la langue des deux autres guides.