Si vous ne pouvez pas l'expliquer simplement, c'est que vous ne le comprenez pas assez bien.
Lorsqu'il s'agit d'expliquer de nouvelles idées aux gens, une nouvelle fonctionnalité que vous voulez intégrer dans le noyau de Joomla, la simplicité est souvent le meilleur point de départ.
Mais cette simplicité est une chose difficile à atteindre. Lorsque l'on observe un design, un code et des inventions remarquables, on constate qu'il existe un grand nombre d'idées, de lignes et de prototypes rejetés sur lesquels ils ont été construits.
Il y a une grande dose de talent qui prend l'idée naissante, la transforme en une idée grossière puis en une fonctionnalité finie et bien pensée. Une fois que vous avez élaboré cette nouvelle idée indispensable, il reste à la tester, à la rédiger et à décrire les cas d'utilisation.
Mais avons-nous besoin d'écrire une telle documentation, devons-nous perdre du temps à expliquer et à décrire ? Mieux vaut passer à la prochaine nouvelle fonctionnalité et faire ce que les codeurs font le mieux... coder.
Et c'est là que se trouve le problème qui se pose à nous. Le codeur n'est pas nécessairement un écrivain, un testeur ou même un anglophone de naissance.
Ce n'est pas parce que le code est écrit avec des mots anglais que le créateur parle couramment la langue par défaut de Joomla. Ainsi, la documentation qui "viendra un jour" n'est jamais écrite, ce jour spécial pour l'écriture du manuel n'arrive jamais et nous n'obtenons pas le statut que mérite cette idée.
Que se passe-t-il quand il n'y a pas de bonne documentation ?
Les testeurs ne disposent donc pas des tests faciles à suivre qu'ils devraient avoir. La fonctionnalité ne reçoit pas les tests dont elle a besoin pour faire partie du noyau, et l'idée languit dans la file d'attente pendant un long moment.
S'il est finalement retenu, les rédacteurs de documents doivent s'efforcer de comprendre ce qu'il fait, comment il le fait et pourquoi il devrait même faire partie du noyau de Joomla. Sans cette connaissance interne, il est vraiment difficile et long de comprendre le travail de quelqu'un d'autre, de comprendre l'idée et de lui rendre justice.
Le temps passe et quelqu'un a besoin de la fonctionnalité, elle s'est faufilée dans le noyau, cachée, utilisée par quelques-uns seulement et ainsi un autre programmeur vient avec une grande idée et fait une extension qui fait exactement ce que la fonctionnalité de base fait déjà, seulement parce qu'ils n'étaient pas au courant.
Cela s'est produit. Comment puis-je le savoir ? Parce que j'ai été là et que j'ai écrit une telle chose, pour découvrir quelque temps après qu'elle était dans le noyau, mais cachée.
C'est une version moderne du vieux proverbe "faute de clou".
Il existe de nombreuses versions, mais en voici une...
Faute de clou, on perdit le fer ;
Faute de fer, on perdit le cheval ;
Faute de cheval, on perdit le cavalier ;
Faute de cavalier, on perdit la bataille ;
Faute de bataille, on perdit le royaume ! »
Ainsi, un royaume fut perdu - tout cela par manque d'un clou.
La documentation est le clou de notre proverbe : tout repose sur une bonne documentation. Le reste de ce qui est nécessaire coulera de source.
Que se passe-t-il lorsqu'il y a une bonne documentation ?
Avec une bonne documentation lorsque le code apparaît pour la première fois dans GitHub, les tests peuvent être écrits de manière logique, et les instructions pour suivre comment installer et utiliser la fonctionnalité seront plus faciles.
Si les instructions de test sont plus faciles à comprendre, non seulement la fonctionnalité sera testée plus tôt, mais elle sera aussi testée mieux et plus profondément, ce qui permettra de découvrir des choses qui n'étaient peut-être pas prévues et qui pourront être corrigées et affinées dès le début.
L'équipe de Joomla Community Magazine, lors d'une de ses réunions de planification très efficaces et jamais détournées, programmera un entretien avec le codeur de la fonctionnalité et le rédacteur des instructions afin d'obtenir un aperçu complet. Cet article sera publié avant la sortie de la fonctionnalité, afin que chacun sache comment et quand l'utiliser.
L'équipe chargée de la documentation se réjouira alors de disposer de documents détaillés et bien rédigés qu'elle pourra récupérer et placer au bon endroit.
OK, mais comment allons-nous résoudre ce problème ?
Quelle est donc cette "recette magique" qui va changer si radicalement la façon dont nous faisons les choses en ce moment, je vous entends hurler ?
Ce sont les accompagnants à la documentation
Un groupe de rédacteurs qui sont prêts à rencontrer n'importe quel codeur pour discuter et comprendre ses plans. Quelqu'un qui peut traduire l'idée de code dans un article bien documenté et illustré qui peut commencer son voyage dans GitHub comme la description de l'idée, mais de transformer à travers le processus d'écriture de prendre la structure et la forme nécessaire pour les différents domaines dans l'écosystème Joomla.
Le processus de discussion de la fonctionnalité avec quelqu'un peut vraiment aider à développer les idées impliquées. Ces écrivains peuvent aider à fournir un moyen systématique d'enregistrer la fonctionnalité à inclure.
Les domaines qui doivent être abordés et détaillés sont les suivants :
- Pourquoi avons-nous besoin de cette fonctionnalité ?
- Quels sont les cas d'utilisation pour lesquels elle nous sera utile ?
- Où la rencontrerons-nous du côté de l'administrateur et du site, si elle y a une influence ?
- Comment l'installer et comment l'utiliser ?
- Détails de configuration, comment le configurer et quelle est la portée de cette configuration ?
- Les tests, comment effectuer les tests et les résultats clairs des tests afin qu'il puisse être facilement compris et mis à l'épreuve ?
- Effets secondaires éventuels, modifications du comportement actuel lorsque cela n'est pas prévu.
- Toute ressource tierce impliquée.
- Une fois que tout cela a été discuté et que le rédacteur du document a compris ce que cela implique, plusieurs versions de l'idée de fonctionnalité doivent être rédigées afin que le codeur et le rédacteur du document soient sur la même longueur d'onde.
Grâce à ces instructions plus détaillées, la conversation sur GitHub devrait être mieux informée. Ce retour d'information sur GitHub peut également contribuer à façonner une partie du document grâce aux perspectives et aux idées des autres participants au processus d'affinage.
Ensuite, une fois le document testé et marqué pour être inclus, les écrits sur GitHub peuvent constituer la base de l'article du magazine et de toute autre documentation à rédiger.
L'article du magazine devrait présenter la fonctionnalité à l'ensemble de la communauté et être utile dans les discussions du JUG pour faire passer le message.
Ainsi, je ne présenterai plus une petite fonctionnalité que j'ai bricolée un après-midi pour m'entendre dire, lors d'un groupe d'utilisateurs de Joomla Londres, qu'elle existe déjà, mais qu'elle est cachée dans le noyau.
Je veux faire partie de l'aventure ! Comment ?
Et maintenant, cher lecteur, c'est votre tour. Si des pensées du type "oui, c'est ce qu'il me faut" et "si seulement ça avait toujours fonctionné comme ça" vous ont traversé l'esprit, n'ayez crainte ! Vous pouvez en faire partie, vous pouvez rejoindre le groupe des documentalistes qui utiliseront le pouvoir de l'écriture pour améliorer le code que les autres créent.
Il existe un groupe appelé Document Buddies sur Mattermost (l'outil utilisé par les équipes de joomla) qui vient d'être créé pour faire ce travail.
Nous voulons que cela reste amusant et productif, utile et collaboratif. Alors venez nous rejoindre, contactez
