DIP S02E01 – La documentation, pour qui ? pour expliquer quoi ? est-ce que cela suffit ?

Pour ce premier épisode de cette toute nouvelle saison de DIP nous nous sommes penché sur le sujet de la documentation.


les présents :

– Jacques – Julien – Louis – Dominique – Boris – Jonathan – Pascal


présentations :

– Louis, était déjà présent lors de la précédente rencontre. Il nous vient tous droit de Paris et est spécialisé en développement back-end PHP. – Julien est venu avec Jacques, il est actuellement stagiaire et également élève chez Open Classroom dans le cursus développeur front-end.

Mais avant de commencer cette séance, comme à l’accoutumée, nous avons partagé nos expériences depuis notre précédente rencontre.

Le Wordcamp BORDEAUX, où Boris et Jonathan se sont rendus durant le mois de Mars. Boris y était notamment invité en tant que conférencié et a notamment évoqué les problématiques d’optimisations des ressources applicables à Wordpress sur sa trollesque présentation Google Slide sobrement intitulé « WPRocket super cache reloaded » ! Tout un programme 🥇. Jonathan pour sa part accompagnait Boris, et lui espérait plutôt trouver des réponses et des astuces techs sur WordPress pour veiller sur le sujet, tout en sachant qu’il devrait effectuer une transmission de savoir prochainement et qu’il se devait de se remettre le nez dans ce CMS très répendu. Il nous a évoqué le contenu d’un livre produit par KINSTA qui lui a été gentillement offert lors de l’évènement. Ce livre est également disponible en ligne, vous pouvez le consulter librement.

Suite à quoi Boris a parlé de la liste d’éco-conception web (NDLR: pour en savoir plus sur ce sujet) et le recommande notamment à Jacques qui est notre expert SPIP. SPIP étant un CMS économique en ressources CPU notamment(NDLR: désolé je n’ai pas de quoi étayer ses propos, si vous en avez, vous seriez aimbale de mes les transmettres).

Bien entendu depuis Jacques c’est inscrit et a participé à cet évènement sans plus attendre 👊


Petite pause dispensable Jacques nous a fait l’honneur d’une petite blague pour l’occasion :

– Bonjour, j’ai un site fait avec Wix – Enchanté ! – J’ai un problème de référencement monsieur – Vous me l’avez déjà dit ça !


Julien en profite pour se présenter, puisque c’est sa première édition DIP. Il est actuellement élève chez Open Classroom et suis la formation développeur front-end. Jonathan en profite pour partager son expérience à propos du mentorat chez Open Classroom. Il en est depuis 1 an et a déjà suivi plusieurs élèves dans leurs formations respectives (développeur front comme chef de projets digital). Il propose également à ses camarades de les parrainer si ceux-ci le souhaitent pour entrer chez OC !

L’existance d’étudiants en Dordogne dans ce secteur ammène également à se poser la question suivant : « Ne pourrait-on pas proposer des ateliers développement à des élèves de Dordogne ? »

Jonathan nous parle également de la WAB à Bergerac qui propose des formations dans le web. Il va notamment y faire une intervention en tant que jury pendant le passage de diplôme « designer web » en juillet. Jacques en profite pour parler du fait que cette école propose des formations certifiantes OPQUAST à tous ses élèves (et ça c’est ultra top ! 👍), ce qui est un gage certain de qualité lors d’un recrutement futur. OPQUAST est une plateforme de qualité web fondée par Elie Sloim. Elle est une pionnière mondiale sur ce sujet, et commercialise des formations et des certificats dédiés à la mesure du degré de maitrise de la qualité web.

– Ce certificat peut-il servir de valeur face à un client, questionne Jonathan ? – Ne le met pas systématiquement en avant, répond Jacques. – Tout dépends avec qui ! Il faut en discuter avec des personnes suffisamments matures pour comprendre l’intérêt d’un tel performance. Cela dit c’est un atout personnel, preuve en est nous l’avons passé avec Jacques sans en avoir particulièrement besoin, réponds Boris à son tour.

Lors d’une précédente rencontre, et également via le canal de discussion par e-mail (donc si vous n’êtes pas inscrit je vous y invite), Jacques avait évoqué de reprendre le module initialement développé par Boris, qui exploitait « Jolitypo », pour l’améliorer et le mettre à jour. Auquel a répondu le principal intéressé que ce n’était pas suffisamment intéressant pour le faire, cela dit JoliTypo (le projet open-source de JoliCode) l’était beaucoup plus !

On a donc enchainé sur une autre idée, un co-développement d’un bloc custom pour Gutenberg Wordpress. D’ailleurs entre temps Graphikart a sorti une vidéo sur le sujet, parfais pour voir ce que cela donne très rapidement (Jacques préconise toujours de lire vos vidéo en 1,5x, en dessous c’est pour les loosers ! (NDLR: là j’extrapole un peu ses paroles 😄)). Ce point n’a pas été retenu pour le moment, il est encore en discussion.

De fils en aiguilles on en arrive à parler de typographie (avec Jacques dans les parages on en est jamais loin 😄) et surtout de la dyslexie. Donc assez logiquement on en est arrivé à parler de Open-Dyslexic une typographie spécifique pour contrer les effets néfastes de cette maladie (Jacques fait partis de ceux qui préfèrent voir les qualitées en chaque défaut, sage position 👼). Les glyphes de cette font sont volontairements non-symétrique, avec un base plus épaisse, afin d’éviter de les confondre par « effet mirroir ».


C’est quand qu’on parle de la documentation là ?

Mais grave ! ça devient longuais votre historique du monde là ! Platon

Il existe au moins deux types de documentations à produire :

– celles destinées aux utilisateurs (installation, usage etc …) – celles destinées aux développeurs

Pour le second type, Jonathan nous parle de sont expérience à base de fichiers readme.md à la racine des dossiers concernés, afin de trouver des informations, certes dispersées au travers du projet, mais disponible à l’endroit où l’on en a besoin (ce qui peut éviter une certaines pollution). D’autant qu’avec des outils comme GitLabl ou GitHub ce type de fichiers est lu automatiquement et visible lorsque l’on navigue dans le projet en ligne, pratique ! Il existe également des outils afin de générer des documentations automatiquement, et rassembler ainsi les informations en un point.

Un des problèmes majeurs de la documentation, est son maintient dans le temps. C’est quelquechose de très chronophage, et très peu valorisable financièrement malheureusement. De cette constatation, Boris ajoute, que pour lui, la seule bonne documentation pour un projet, ce sont les tests unitaires. Et que les documentations d’installation (à destination des dévs) & les cookbooks sont de bonnes choses si elles sont accompagnés de tests pour vérifier que cela marche. Il profite de l’occasion pour expliquer la pyramide des tests :

– tests de haut niveau – tests d’intégration – tests unitaires

pyramide des tests

parlons un peu des outils à voir pour faire vos tests :

– doc side-to-side : pyccoon, docsify etc… – doc à génération à part : doxygen, jekyll, gitbook, vuepress etc… – générer des schéma : PlantUML, WebSequenceDiagramm etc… – pour des tests : puppeteer, selenium, karma etc…

A voir également, la conférence sur la documentation au PHP Tour de Montpellier en 2018, animée par Sarah Haim.

Chacun y trouvera son bonheur, mais ne serait ce pas là un excellent sujet à pousser plus loin ? et si quelqu’un prenaient un de ces outils et faisaient une petite démo aux autres lors d’un prochain rassemblement ? Matérialiser des propos … why not !

🤝 Merci pour cette rencontre, on se donne rendez-vous à la prochaine en date du 03 juin 2019 (save the date!)

Jonathan

Ce projet est maintenu par dev-in-perigueux