« Pourquoi ce site utilise Polylang plutôt que WPML ? » Cette question, posée par une nouvelle équipe reprenant la maintenance d’un site multilingue, aurait dû trouver sa réponse en cinq minutes dans une documentation existante. Elle a en réalité déclenché six semaines d’hésitation, où l’équipe a exploré l’hypothèse d’une migration vers WPML avant de découvrir, par recoupement avec d’anciens tickets, que ce choix avait déjà été étudié et écarté trois ans plus tôt pour des raisons précises qui restaient valables.
Ce cas illustre un problème récurrent lors du changement d’agence sur un site multilingue : l’architecture technique se transmet, mais le raisonnement qui l’a produite se perd, et l’équipe reprenante finit par redécouvrir à ses frais des arbitrages déjà tranchés.
Ce qui se transmet naturellement, et ce qui ne se transmet pas
Un transfert de site multilingue s’accompagne presque toujours des mêmes livrables : accès aux hébergements, export de base de données, liste des extensions actives, parfois un schéma d’architecture technique. Ces éléments décrivent l’état du système à l’instant T, mais aucun d’entre eux n’explique pourquoi cet état a été atteint plutôt qu’un autre.
Sur ce projet, le schéma transmis montrait bien que Polylang gérait quatre langues avec des sous-dossiers de langue et une synchronisation manuelle des menus. Il ne disait rien sur le fait que cette synchronisation manuelle avait été un choix délibéré, après un incident où la synchronisation automatique avait dupliqué des liens de menu vers des pages supprimées. Sans cette information, la nouvelle équipe a d’abord considéré cette synchronisation manuelle comme une négligence à corriger.
Le document qui aurait évité six semaines de tâtonnement
Après cet épisode, un document de transmission a été rédigé rétroactivement, avec une structure volontairement différente d’un schéma d’architecture classique : chaque section part d’une décision prise, pas d’un composant technique.
- Décision : quel choix a été fait (exemple : Polylang plutôt que WPML).
- Alternatives étudiées : ce qui a été envisagé et pourquoi ça a été écarté.
- Contrainte à l’origine : le budget de licence, la complexité de migration, la compatibilité avec une extension e-commerce existante…
- Ce qui remettrait cette décision en cause : les conditions qui justifieraient de la revoir aujourd’hui.
Pour l’exemple de Polylang, la section « alternatives étudiées » mentionne que WPML avait été écarté à l’époque à cause d’un conflit documenté avec une extension de champs personnalisés alors utilisée sur le site, un conflit qui n’existe peut-être plus avec les versions actuelles des deux extensions. Cette nuance change tout : elle transforme un choix qui semblait arbitraire en une décision conditionnelle, à réévaluer si la contrainte d’origine a disparu.
La liste des pièges déjà rencontrés
Une deuxième section du document, tout aussi utile, recense les incidents passés et leur résolution, indépendamment de l’architecture générale :
| Incident | Cause | Résolution appliquée |
|---|---|---|
| Menus dupliqués après mise à jour | Synchronisation automatique de Polylang avec des menus contenant des liens vers du contenu supprimé | Synchronisation désactivée, mise à jour manuelle des menus par langue |
| Balises hreflang manquantes sur les pages d’archive | Extension SEO configurée avant l’activation complète de Polylang | Reconfiguration complète de l’extension SEO après audit |
Sans cette liste, une nouvelle équipe qui retombe sur un problème déjà résolu a toutes les chances de repartir de zéro, potentiellement vers une solution différente, moins adaptée aux contraintes réelles du projet, ou simplement plus longue à mettre en œuvre qu’un correctif déjà connu.
Quand documenter, et par qui
Le moment le plus efficace pour documenter une décision d’architecture n’est pas au moment de la transmission, sous la pression du départ imminent d’une équipe, mais au moment même où la décision est prise, quand le raisonnement est encore frais. Sur ce projet, la pratique adoptée depuis consiste à ajouter systématiquement une note dans le gestionnaire de tickets dès qu’un choix d’architecture significatif est arbitré, avec les mêmes quatre rubriques que le document de transmission.
Cette note n’a pas besoin d’être exhaustive : quelques phrases suffisent, tant qu’elles couvrent la contrainte d’origine et les alternatives écartées. L’objectif n’est pas de produire un rapport, mais de laisser une trace suffisante pour qu’une personne extérieure au raisonnement initial ne parte pas d’une hypothèse fausse.
Un schéma d’architecture dit ce qui existe. Un document de transmission dit pourquoi ça existe. Sur un site multilingue, où chaque contrainte de langue s’accumule aux précédentes, c’est ce deuxième document qui évite à l’équipe suivante de redéfaire un travail d’arbitrage déjà fait.
Ce que ce document ne remplace pas
Cette documentation d’architecture ne dispense pas d’une passation orale, quand elle est possible, ni d’un audit technique indépendant par la nouvelle équipe pour vérifier que l’état réel du site correspond bien à ce qui est décrit. Un document de transmission peut lui-même devenir obsolète si une décision a été modifiée sans que la documentation ne suive. Il reste néanmoins le meilleur point de départ disponible, très supérieur à l’absence totale de contexte qui est, en pratique, la situation la plus fréquente lors d’un changement d’agence.
En résumé
La transmission d’un site multilingue échoue rarement sur les accès techniques ou l’export de données : elle échoue sur la perte du raisonnement derrière chaque choix d’architecture. Documenter systématiquement la contrainte d’origine, les alternatives écartées et les conditions qui justifieraient de revoir une décision coûte quelques phrases au moment où le choix est fait. Cela évite, comme sur ce projet, plusieurs semaines de tâtonnement inutile à l’équipe qui reprend le site ensuite.
