Bonnes pratiques¶
Onboarding, knowledge sharing et documentation d'accueil pour que chaque nouveau membre soit opérationnel rapidement.
L'onboarding comme investissement¶
Le temps passe a onboarder un nouveau membre est un investissement a rendement rapide. Un onboarding structure permet au nouveau dev d'être productif en quelques jours plutôt qu'en quelques semaines. Un onboarding bacle crée de la frustration, des erreurs et parfois des départs prematures.
L'onboarding est un produit
Traitez votre documentation d'onboarding comme un produit : elle a des utilisateurs (les nouveaux), des retours (ce qui manquait), et doit être mise à jour régulièrement.
Les trois horizons de l'onboarding¶
Premier jour : survivre et se sentir accueilli¶
Objectif : le nouveau peut accéder aux outils et sait a qui parler.
- Accès aux outils (forge, chat, wiki, VPN, cloud)
- Setup du poste de travail documente et testable
- Présentation de l'équipe et des canaux de communication
- Premier commit — même mineur (correction typo, ajout dans AUTHORS)
- Buddy désigné pour les questions informelles
Première semaine : comprendre le système¶
Objectif : le nouveau comprend l'architecture et peut lire la base de code.
- Vue d'ensemble de l'architecture (diagramme, session avec un tech lead)
- Premier ticket simple en autonomie avec review par le buddy
- Accès aux runbooks et aux post-mortems récents
- Participation a une rétrospective ou a un standup
Premier mois : contribuer de façon autonome¶
Objectif : le nouveau peut livrer une feature complète sans assistance constante.
- Première feature complète du ticket à la production
- Participation a une code review (comme reviewer)
- Identification des zones encore floues → mise à jour de la doc
Documentation d'accueil¶
La documentation d'accueil répond aux questions que tout nouveau se pose mais n'ose pas toujours poser.
Structure recommandee¶
docs/
onboarding/
README.md # Ou commencer
setup.md # Installation du poste
architecture.md # Vue d'ensemble du systeme
conventions.md # Standards de code et de commits
workflows.md # De l'issue au deploy
glossaire.md # Acronymes et termes internes
contacts.md # Qui contacter pour quoi
Ce que les nouveaux cherchent¶
| Question | Document |
|---|---|
| Comment installer mon environnement ? | setup.md |
| Comment démarrer le projet en local ? | setup.md ou README |
| Quelle est l'architecture globale ? | architecture.md |
| Comment nommer mes branches et commits ? | conventions.md |
| Quel est le chemin d'un ticket au deploy ? | workflows.md |
| Qui peut m'aider sur la partie auth ? | contacts.md ou tags dans la forge |
| Que signifie "CQRS" dans ce contexte ? | glossaire.md |
La documentation qui ment
Une documentation d'installation qui ne fonctionne pas est pire que pas de documentation — elle fait perdre des heures et entame la confiance. Testez votre setup.md sur une machine vierge au moins une fois par trimestre.
Le système de buddy¶
Un buddy est un membre experimente de l'équipe assigne au nouveau pour ses 4 a 8 premières semaines. Ce n'est pas un manager — c'est un guide informel.
Rôle du buddy¶
- Répondre aux questions "betes" sans jugement
- Signaler les usages informels non documentes
- Faire les premières reviews avec bienveillance
- Donner un feedback direct sur les premiers livrables
Ce que le buddy n'est pas¶
- Le seul point de contact — le nouveau doit aussi apprendre a naviguer seul
- Un formateur a plein temps — le buddy garde sa propre charge
- Un filtre entre le nouveau et le reste de l'équipe
Rotation des buddies
En faisant tourner le rôle de buddy, vous renforcez la capacité de l'équipe a expliquer le système et vous evitez la surchargé sur une seule personne.
Knowledge sharing¶
Tech talks internes¶
Des presentations courtes (15-30 minutes) sur un sujet technique, ouvertes à toute l'équipe ou l'organisation. Format : demonstration, retour d'expérience, deep dive.
Fréquence recommandee : bi-mensuel ou mensuel. Ne forcez pas — un tech talk volontaire est toujours meilleur qu'un tech talk obligatoire.
RFCs (Request for Comments)¶
Un RFC est un document court qui propose un changement significatif et invite les commentaires avant implémentation.
Structure minimale d'un RFC :
# RFC-042 : Migrer vers PostgreSQL pour les sessions
## Contexte
Nos sessions Redis saturent a partir de 10k utilisateurs concurrents.
## Proposition
Utiliser PostgreSQL avec pgbouncer pour les sessions persistantes.
## Alternatives considerees
- Passer a Redis Cluster → cout infrastructure eleve
- Garder Redis avec TTL reduit → ne resout pas le fond
## Impact
- Migration de donnees necessaire
- Mise a jour du schema de session
- Perf estimee : +20ms en p99 (acceptable)
## Decision
En attente de feedback jusqu'au 2025-05-01.
Guildes et chapters¶
Une guilde (ou chapter) rassemble les personnes partageant une expertise (sécurité, frontend, data) independamment de leur équipe. C'est un espace de partage horizontal.
Activités typiques : newsletter technique, revue de vulnérabilités, choix de dépendances partagees.
Living documentation¶
La living documentation est documentee au plus pres du code et mise à jour automatiquement quand possible.
| Type de documentation | Approche living |
|---|---|
| Architecture | Diagrammes as-code (Mermaid, PlantUML dans le dépôt) |
| API | Générée depuis le code (OpenAPI, docstrings) |
| Décisions techniques | ADR (Architecture Décision Records) versionnees |
| Runbooks | Dans le dépôt, linkables depuis les alertes |
| Onboarding | Testée sur chaque arrivee, issue ouverte si erreur |
Pratiques par profil et moment¶
| Pratique | Quand | Qui |
|---|---|---|
| Setup buddy | J0 d'un nouveau membre | Lead ou senior volontaire |
| Premier commit trivial | J1 | Nouveau + buddy |
| Session architecture | Semaine 1 | Tech lead + nouveau |
| Premier ticket solo | Semaine 1-2 | Nouveau, review par buddy |
| Tech talk | Quand quelqu'un a appris quelque chose | Tout développeur |
| RFC | Avant tout changement important | Auteur + reviewers désigné |
| Mise à jour onboarding | À chaque arrivee | Nouveau + responsable doc |
| Guilde mensuelle | Mensuel | Membres de la guilde |
Points clés¶
- Structurez l'onboarding en trois horizons : jour, semaine, mois
- La documentation d'accueil est un produit — testez-la et maintenez-la
- Le buddy accéléré l'intégration sans surcharger le reste de l'équipe
- Les tech talks et RFCs sont les mécanismes de knowledge sharing les plus scalables
- La living documentation se maintient parce qu'elle vit pres du code
Précédent : Inner source | Suite : Cas avances