Comment créer et gérer une documentation de qualité - Podcast

Notre tout premier épisode du podcast Change Mode démarre sur les chapeaux de roues avec un merveilleux invité de l' équipe Symfony, Ryan Weaver. Le responsable de la documentation Symfony et l' auteur desSymfonyCasts nous gardent tous sous contrôle lorsqu'il s'agit de développement Symfony. Rejoignez-nous dans cet épisode où Ryan nous explique comment débuter dans l'open source, ses méthodes pour créer et gérer une bonne documentation et des screencasts (y compris ces redoutables traductions), et comment concilier l'open source et la vie de famille.

Faites un don sur la page GoFoundMe de Ryan pour le soutenir dans sa lutte contre le cancer.

Transcription du podcast

Nous avons utilisé ChatGPT pour améliorer la grammaire et la syntaxe de la transcription.

Ryan : Je fais partie de l'équipe principale du Symfony Framework. Symfony est un framework PHP utilisé pour construire des applications web, mais il se compose également de bibliothèques indépendantes. Même les personnes qui n'utilisent pas directement Symfony, comme celles qui travaillent avec Drupal ou Laravel, bénéficient de ses composants.

Je me concentre beaucoup sur la documentation et je crée des tutoriels pour SymfonyCasts, le site de screencasting pour Symfony. Je contribue également à d'autres parties de l'écosystème open-source PHP et Symfony.

Marine : C'est bien. Cela m'intéresse. Comment avez-vous commencé à travailler dans l'open source ? Était-ce un accident ou un moment décisif ?

Ryan : C'est généralement une sorte d'accident pour tout le monde.

Marine : Oui, en général, quelqu'un vous met sur la voie.

Ryan : Exactement. Il y a longtemps, j'écrivais des articles de blog sur Symfony parce que c'est ce que tu fais en tant qu'intello pour comprendre les choses. Quand Symfony 2 est sorti, il s'agissait d'une réécriture majeure. Le développeur principal, Fabien, avait besoin de quelqu'un pour écrire la documentation. D'une manière ou d'une autre, il m'a remarqué à travers mes articles de blog et m'a demandé si je voulais écrire la documentation pour Symfony 2. Bien sûr, j'ai dit oui. Avec le recul, il était probablement soulagé de confier cette tâche à quelqu'un d'autre.

Marine : Incroyable. C'est donc Fabien Potencier qui te l'a demandé.

Ryan : Oui, en anglais, on dit "voluntold". Tu n'es pas volontaire, quelqu'un te demande volontairement de le faire.

Marine : Intelligent. C'est de sa faute.

Ryan : Oui.

Marine : Ok, dûment noté.

Ryan : Et puis ça fait boule de neige.

Marine : Exactement. Tu commences par une petite chose et ensuite tu es connu pour ça. C'est trop tard.

Ryan : Oui. Et puis tu es excité parce que tu sais.

Marine : Donc tu contribuais déjà en écrivant des articles de blog. Ce n'est pas une contribution open-source ?

Ryan : Oui, c'est une contribution à l'open source. Je devrais m'en souvenir parce que beaucoup de gens demandent comment ils peuvent contribuer à l'open source, pensant que c'est une question de code. Mais ce n'est pas toujours facile, surtout avec quelque chose d'aussi robuste que Symfony. Parfois, contribuer peut être aussi simple que de poster des solutions sur votre blog ou sur les médias sociaux. J'aimerais qu'il y ait plus de gens qui le fassent parce que cela aide la communauté.

Marine : Oui, c'est quelque chose que j'aime dans PHP et Drupal. Vous ne vous souciez pas seulement du code, mais aussi de tout type de contribution, comme la documentation, qui est souvent négligée mais tellement utile. C'est le point d'entrée pour les nouveaux venus. Si vous écrivez un article de blog, c'est que vous faites de l'open source. Tant mieux pour vous.

Ryan : Ce billet de blog peut être un paragraphe et deux blocs de code.

Marine : Oui, les principaux contributeurs trouvent parfois des solutions dans leurs anciens articles de blog. C'est utile pour toi aussi.

Ryan : Exactement.

Marine : Donc, les articles de blog, puis la documentation pour Symfony 2, ce qui a dû être une tâche énorme. Avez-vous eu de l'aide ? Comment cela a-t-il fonctionné ?

Ryan : Pas au début, mais ce n'était pas grave car je n'avais pas encore d'enfant. Au fil du temps, d'autres ont commencé à contribuer de plus en plus, et maintenant il y a une équipe Symfony d'environ 40 personnes qui travaillent sur la documentation. Au départ, j'étais un jeune développeur inexpérimenté, et l'excellente documentation de Symfony était cruciale pour moi. Je voulais rendre Symfony 2 accessible et invitant pour les nouveaux développeurs.

Marine : Est-ce que cela a commencé par une volonté de rendre service, ou étiez-vous déjà passionné par le partage et l'éducation ?

Ryan : J'aime rendre la pareille parce que ça fait du bien, mais c'est aussi le plaisir d'ouvrir le code et de voir comment les choses se connectent. Si tout le monde devait comprendre tout seul, ce serait une perte de temps. Partager ce que l'on sait permet de construire une base pour les autres.

Marine : Tu as donc commencé à contribuer au code ?

Ryan : Oui, cela me dérange quand les choses sont répétitives et inefficaces. J'ai commencé à contribuer davantage autour de Symfony 3, en créant le maker bundle pour générer du code et améliorer l'expérience du développeur. Il s'agit d'un développement axé sur la douleur - supprimer les frictions pour créer une expérience plus fluide pour les développeurs.

Marine : J'adore cela parce que vous faites toujours de la documentation, mais d'une manière différente.

Ryan : C'est un bon point.

Marine : Si tu veux expliquer quelque chose et que tu réalises que c'est trop complexe, est-ce que c'est à ce moment-là que tu contribues aussi au code ?

Ryan : Oui, si vous écrivez de la documentation ou créez des screencasts et que vous trouvez quelque chose de douloureux, c'est là que vous réalisez que cela doit être corrigé. Les utilisateurs ressentent des douleurs que les responsables de la maintenance ne connaissent peut-être même pas. Si vous pouvez articuler et résoudre ces problèmes, c'est puissant. Même l'ouverture d'un ticket peut être une contribution utile.

Marine : Ouvrir un ticket pour de la documentation fonctionne aussi ?

Ryan : Oui, ouvrir un problème avec des détails et des solutions possibles est une bonne façon de contribuer. C'est moins intimidant que de créer directement une pull request.

Marine : Intéressant. Comment es-tu passé des contributions de base à SymfonyCasts ?

Ryan : Quand Symfony 2 est sorti, nous avons fait des formations en personne, mais ce n'était pas accessible à tout le monde. Nous avions besoin d'offrir cette expérience à un prix abordable pour les petites entreprises. SymfonyCasts est né de ce besoin, et c'est formidable qu'il aide aussi à financer l'open source de Symfony.

Marine : Votre femme vous aide dans cette tâche ?

Ryan : Oui, elle est notre développeuse frontale. Je veux tout donner gratuitement, mais elle s'assure que nous pouvons aussi payer notre maison et notre nourriture.

Marine : L'équilibre entre le fait de donner et de gagner sa vie est une grande question dans l'open source.

Ryan : Oui, c'est un problème classique. Des projets comme la fondation PHP et la fondation Drupal aident en payant des développeurs pour travailler sur des initiatives importantes.

Marine : Les entreprises doivent aussi rendre la pareille. Chez Platform.sh, nous sponsorisons Symfony et d'autres projets open-source. Cela fait une grande différence.

Ryan : C'est vrai.

Marine : Tu as amené ton enfant à SymfonyCon. Comment le fait d'avoir un enfant affecte-t-il vos contributions à l'open-source ?

Ryan : Cela change tout. Avant les enfants, vous pouviez faire de l'open source pendant votre temps libre. Avec des enfants, vous avez besoin de monétisation pour que cela fasse partie de votre journée de travail. Je fais mon travail open-source entre 9 et 5 heures parce que SymfonyCasts le supporte.

Marine : Vos enfants s'intéressent-ils au développement ?

Ryan : Pas du tout. Mais emmener mon fils à des conférences, c'est lui donner une expérience du monde et lui permettre de rencontrer des gens d'horizons différents.

Marine : C'est formidable. Qu'en est-il de la contribution à d'autres projets ?

Ryan : Je me concentre principalement sur Symfony, mais j'ai commencé à contribuer à certains outils JavaScript utilisés à la fois dans Symfony et Ruby on Rails. C'est génial d'apprendre d'une autre communauté et d'appliquer ces connaissances à Symfony.

Marine : Est-il possible de contribuer aux SymfonyCasts ?

Ryan : Il est difficile de créer des screencasts. Bien que nous acceptions les contributions, c'est une tâche spécialisée. Nous avons des scripts et des blocs de code disponibles gratuitement pour rendre le contenu plus accessible.

Marine : Qu'en est-il de la traduction de la documentation ?

Ryan : La traduction est un défi car la documentation change fréquemment. Cependant, les outils de traduction automatique s'améliorent. Nous traduisons nos scripts et sous-titres sur SymfonyCasts en espagnol et prévoyons d'ajouter d'autres langues.

Marine : Les communautés locales créent également des bases de connaissances dans leur langue. Il s'agit de rendre l'information accessible.

Ryan : Oui, les communautés indépendantes passionnées jouent un rôle crucial.

Marine : Qu'avez-vous appris sur l'enseignement et le partage des connaissances ?

Ryan : Il faut raconter une histoire, construire quelque chose de concret qui résout un problème. Il faut montrer aux gens les étapes que vous avez suivies pour résoudre le problème, et pas seulement le résultat final.

Marine : Comprendre la logique aide à la reproduire, pas seulement à suivre les étapes.

Ryan : Exactement.

Marine : Si tu avais la permission de faire n'importe quoi pendant une journée, qu'est-ce que ce serait ?

Ryan : J'irais à Cedar Point, un parc d'attractions, et je ferais des montagnes russes toute la journée. Ce n'est pas réaliste avec un enfant de 7 ans, mais ce serait amusant.

Marine : Et si tu pouvais inventer une nouvelle permission ?

Ryan : Un voyage plus rapide que la lumière. J'adore l'espace et la science-fiction. Nous devons explorer l'univers sans les effets déprimants de la dilatation du temps.

Marine : Quel est ton plus grand pouvoir ?

Ryan : Jouer avec des enfants de moins de sept ans. J'adore leur causer des ennuis et m'amuser avec eux. C'est un super pouvoir.

Marine : Parents, ne laissez pas vos enfants sans surveillance avec Ryan !

Ryan : On va s'amuser, mais il y aura une émeute.

Marine : Merci, Ryan. C'était un plaisir de t'avoir avec nous. J'attends avec impatience le futur de SymfonyCasts.

Ryan : Moi aussi. Merci de m'avoir reçu.