Documenter mon projet open-source rapidement

Documenter mon projet open-source rapidement

Je reçois beaucoup de questions sur les outils à utiliser. J’ai décidé d’y répondre ici.

Comment documenter de façon économique un projet open-source, fait sur le temps libre ?

Les générateurs statiques sont très efficaces, et en version hébergée pour vous, il n’y a pas, en 2020, tant de solutions que cela. Mes recherches ont été faciles.

En fait, j’ai identifié 4 solutions pratiques qui supportent le Markdown :

  • Github Pages : un Jekyll rattaché à vos projets hébergés sur Github
  • Gitlab Pages : à vous de choisir le générateur statique qui vous convient.
  • ReadTheDocs (gratuit pour les projets open-source) : choisissez entre deux parfums, un Sphinx ou un MkDocs, pour utiliser le format de fichier qui vous convient le mieux.
  • Gitbook (gratuit pour les projets open-source) : solution propre, l’équipe est à Lyon.

Vendredÿ: un peu de LSF, le kilo-girl et PHP est très vieux

Disclaimer: j’ai emprunté ce terme de Vendredÿ chez Alsacreations.

Pour moi, il s’agit d’une veille des choses qui m’ont faite rire, étonnée et interpellée. Je l’envoie par e-mail chaque semaine à mes collègues, et je me suis dit « Pourquoi ne pas en faire profiter tout le monde ? »

[talk] Sans documentation, la fonctionnalité n’existe pas !

Voici la vidéo, les slides et surtout les liens complémentaires de la conférence que j’ai eu l’honneur d’animer au PHP Tour 2018 à Montpellier. J’avais intitulé ma session Sans documentation, la fonctionnalité n’existe pas ! et le titre avait déjà amené beaucoup de débats avec mes pairs. Je vous laisse donc m’écouter, me lire et, si le sujet vous intéresse, approfondir la question par vous-même.

La vidéo de la session

Les slides de « Sans documentation, la fonctionnalité n’existe pas »

J’ai pris soin de garder les animations, c’est pourquoi vous avez un grand nombre de diapos : quand il y a deux versions, c’est que j’ai gardé les versions avant et après l’animation.

Les liens complémentaires

Durant ma présentation, je cite des outils ou je référence le travail d’autres personnes, voici les liens complémentaires.

 

Qu’ai-je appris dans mes études supérieures qui me sert encore aujourd’hui ?

Qu’avez-vous appris dans vos études supérieures qui vous serve encore aujourd’hui ?demande Eric Daspet.

Je voudrais répondre à cette question précise car, contrairement à beaucoup de mes collègues passés, présents et futurs(?), je suis allée à l’Université. Vous trouverez sur mon profil LinkedIn/Viadeo le détail de mon cursus.

J’ai appris l’usage de Linux, ce qu’est l’opensource, lire des textes de lois (pour lire le code du travail) et les comprendre, faire une synthèse de mes idées, et à l’inverse développer mes idées, présenter à l’oral devant un public pas intéressé, travailler en binôme ou en petit groupe, lire la doc/chercher de l’aide, préparer mon boulot avant de m’y mettre, être fière de mon boulot, et LE truc précieux : faire des sauvegardes de mon travail. Cela me sert encore aujourd’hui dans mon métier.

Woman in Blue Reading a Letter, Johannes Vermeer painting

Johannes Vermeer [Public domain], via Wikimedia Commons

Ah je n’ai pas été en école d’ingé mais à la fac, c’est peut-être le détail. Les élèves en école d’ingénieur que j’ai côtoyé étaient parfois un peu trop choyés pour se rendre compte de la chance qu’ils avaient au niveau des moyens fournis.

Sur les savoirs plus informels, qui me servent encore, mais pas forcément dans mon métier, j’ai appris à m’y retrouver sur un campus universitaire et cela m’a appris à m’orienter (parfait quand tu es formatrice/consultante et que ton lieu de travail n’est pas fixe) et à demander mon chemin pour être à l’heure, boire du café, ne pas préjuger des compétences des gens selon leur apparence (quand le sysadmin de ton université ressemble à un clochard et le prof de réseaux à un poivrot, au hasard), écouter et prendre des notes (utile durant les conférences), mémoriser des tas de trucs grâce à des techniques de mémorisation, apprécier le bon café, partager l’information, et dénicher les bons livres dans les bibliothèques.

Investir et former

Même le stage de fin d’étude n’est qu’une autorisation à être un peu moins productif ou à passer quelques jours à lire des documentations.

Hé bien, là encore, mon stage de fin d’études a été prétexte à une offre d’embauche, et j’ai mis les mains dans le code, si je puis dire, sur une partie annexe et non-commerciale du projet.

FEMA - 19762 - Photograph by Greg Henshall taken on 11-28-2005 in Louisiana

Je comprends néanmoins ce que soulève Eric Daspet comme problème : l’investissement (monétaire, eh oui) sur les savoirs et le fast-savoir.
Les formations sont très bien comme démarreurs, ensuite, il vous faudra digérer tout ce qui a été vu, le refaire. Ce n’est pas après quelques jours sur une technologie ou une méthode que vous serez au point. Pire, il faudra être confrontée à l’échec pour apprendre. (Comment croyez-vous que j’ai appris pour les sauvegardes ?)
Et dans le pire des cas, il est attendu que vous sachiez déjà, ou que vous soyiez prêt à vous former par vous-même, sur votre temps personnel.

C’est un sujet de longue haleine, sur lequel je peine à me faire un avis, la veille techno sur temps de travail et hors temps de travail, donc je ne développerai pas mes idées maintenant.

La Documentation comme une punition

L’autre matin encore, j’ai entendu mes collègues parler de leurs tâches possibles pour les prochaines heures, et l’un dire à l’autre : « Tu peux écrire la documentation de telle Story, si tu veux » et l’autre répondre : « Non, je ne suis pas désespéré à ce point. »

Mes collègues sont formidables et ils me donnent l’occasion de parler de cette tradition de voir la documentation de ses développements comme une punition. Évidemment, ce n’est pas la partie la plus sexy du code de se taper la Documentation. Evidemment, c’est pas l’fun de devoir expliquer ce qu’on a brillamment conçu avec son cerveau super-intelligent pour que d’autres péons puissent comprendre le fonctionnement, sinon l’intention de votre création.

Pillory (PSF)

Cloué au pilori, la punition

Simplement, si vous avez fait vos développements super-cools, qui va savoir les utiliser hormis vous ? Qui va savoir qu’ils existent si vous n’en faites aucune promotion ?

Pour moi, la documentation sert à plusieurs personnes :

  •  Le développeur qui est forcé d’expliquer et remettre à plat l’utilité et le fonctionnement de son oeuvre.
  • Les utilisateurs qui veulent s’en servir, qu’ils soient utilisateurs techniques ou non
  • Les autres collègues, incluant le développeur lui-même dans le futur, qui sont parfois forcés de reprendre le code de quelqu’un d’autre. On disait parfois en riant : « ça a été difficile à écrire, ça doit être difficile à lire », en réalité, c’est une blague, faut pas le faire.
  • La partie marketing qui peut ainsi affirmer que la fonctionnalité existe et qu’il est possible de s’en servir

Quand vous voyez la Documentation comme une punition, en réalisé, vous punissez les personnes que je cite dans ma courte liste. Et quand j’évoque la Documentation, cela ne se limite pas aux pages écrites dans un bon anglais/français, avec des jolis exemples théoriques de code. Cela inclut les bons messages d’erreurs, les informations retournées par l’API, et les commentaires dans le code, ainsi que les diagrammes concernant l’architecture et le pourquoi de ces choix.

Le CommitStrip m’y a refait penser au point que je me suis dit que j’allais écrire un billet sur le sujet : http://www.commitstrip.com/fr/2016/07/27/documentation-just-before-vacation/

Il est temps de réfléchir et mûrir un peu sur ce sujet, ne croyez-vous pas ?

 

La keynote Mix IT édition 2016 (compte-rendu)

Ce n’était pas la première fois que je participais à Mix IT, et j’espère que ce ne sera pas la dernière. Il s’agit de deux jours de conférence, à Lyon, sur des sujets autour de l’informatique : technique et pratiques, notamment agiles. C’est en général passionnant parce que les sessions sont variées et les orateurs viennent d’horizons très différents.

mixit-banner

J’ai poussé fort pour que dans mon entreprise, on envoie des salariés à cet événement, et ça a été possible.

Ce qui me plaît dans Mix IT est aussi le démarrage de journée, tous les orateurs viennent pitcher leur session en 30 secondes, pour donner envie. Parfois, même moi qui a fait mon programme à l’avance, je change d’idée et je vais voir une session qui ne m’avait pas attirée sur le planning.

Keynote : agilité et pédagogie

Chrisian DEN HARTIGH

La Keynote de démarrage frappe fort. Un enseignant de collège, nous fait un REX sur ses pratiques agiles en classe.

Les bureaux des élèves sont en rond autour de tables supportant la documentation (dictionnaires et ouvrages de référence). Du coup, ils sont tous au premier rang. Difficile de sa planquer dans cette configuration. Pour d’autres phases de travail, les tables sont changées de place, et ce sont des ilôts pour encourager le travail en petit groupe.
Sur les groupes et dynamiques de groupe, il nous explique l’holarchie. Les élèves sont par classe d’âge, sans plus d’affinité que cela.

L’enseignant déplore qu’il a 100 nouveaux élèves chaque année et aucun retour sur ses pratiques. Il ne fait partie de leur vie scolaire qu’une seule année.

Ce qui m’a interpellée :

  • Tous les 15 sujets de rédaction de l’année sont donnés au début de l’année (ex : repas qui se termine mal). Les élèves préparent leur rédaction à la maison, en suivant un modèle (la double molécule) quant au déroulement de leur histoire. En réalité, s’ils n’ont rien préparé, ce n’est pas non plus un handicap. Puis en classe, ils échangent entre eux car les individus et interactions sont plus importants que les outils (hoho, l’avez vous vu le Agile Manifesto ?). Ensuite ils écrivent leur rédaction.
  • Les élèves ont des fiches d’auto-évaluation et choisissent sur quoi ils veulent s’améliorer.
  • Le papier de la colère : feuille identifiée comme « le papier de la colère » à froisser violemment en cas de colère.
  • Le smiley « doigt sur la bouche » à poser devant l’élève trop bruyant (chut).
  • Pour tous les travaux notés, les élèves ont accès à beaucoup de documentation.
  • Certains exercices ont une double réponse : une fois faits par l’élève, une fois fait avec des dés. Par ex, un exercice de grammaire avec les terminaisons -é -er et -és à placer est réalisé en deux colonnes. L’élève remplit avec son savoir, puis en suivant le dé.
  • Le Kanban en classe. Hé oui, la visualisation de ce qui est en-cours et de ce qui reste à faire est très puissante.

La citation

« J’ai deux moyens de communication, digital et numérique. »

En savoir +

https://pedagogieagile.com

Ensuite, je suis restée assise. Bon j’étais un peu soufflée, il faut bien le dire. Et la conférence suivante toujours dans le cadre de la keynote était fort intéressante.

La confiance en soi, ça ne sert à rien

Laure JOUTEAU

Laure Jouteau nous explique qu’en fait, pour changer de voie, ou se lancer dans quelque chose de nouveau, la confiance en soi n’est d’aucune utilité.

Inutile donc de rester paralysé par le conformisme, ou d’essayer de se rassurer en cherchant des bonnes raisons de se lancer.

Ce qui m’a interpellée :

  • Défi : faites LA chose que vous ne faites pas parce que vous n’osez pas, faites le pour vous, par pur égoïsme
  • On essaie toujours de rationnaliser par une idée de génie, un vocation alors qu’il faut une autorisation de se planter
  • La nouveauté est toujours assortie de trouille et c’est ok.

La citation

« On n’est pas la bonne personne pour réaliser ses rêves, on devient cette personne en le faisant. »

En savoir +

La vidéo de la conférence

Le texte du talk « La confiance en soi ça ne sert à rien »

 

Ce que m’a appris le HackDay Symfony

Tout d’abord, on pourrait croire que j’ai hacké comme une petite folle ce jour là, eh non…mes responsabilités parentales ont fortement limité mon champ d’action.
Cependant, voici ce que j’ai appris durant le HackDay Symfony lyonnais du 5 juillet 2014 :

  • demandez le minimum aux gens
  • encouragez les dès le départ
  • soyez attentifs à votre environnement : les gens aiment résoudre des problèmes (poussette dans l’escalier, intitulé des tickets)
  • le temps passé ensemble est précieux (ma fille qui me dérange tout le temps, partager autour d’une pizza)
  • tout le monde peut faire avancer les choses (même un tout petit point peut aider, parler peut donner des idées)

Allez lire le compte-rendu sur le site de l’AFUP.

Sketching Notes #2 : inspiration bande-dessinée

En publiant mon dernier billet sur le sujet des prises de notes visuelles, ou sketchnig notes, je me suis remémorée tout ce que j’avais oublié de mettre dans mon billet.

Le plus dur est de se lancer. Si vos notes sont pour vous, autant vous lancer tout de suite, à la prochaine réunion, ou à la prochaine vidéo de conférence ou tutoriel que vous regarderez. Voire lancez vous au prochain épisode de série, si vous ne suivez que d’un oeil distrait. J’imagine qu’on peut même prendre des notes visuelles durant un jeu télévisé, ou en regardant d’autres gens jouer à un jeu vidéo.

Les croquis d’audience, notes vivantes

Je voulais ajouter que cette idée de dessiner ce qui se passe n’était pas nouvelle, pensez par exemple au croquis d’audience qui permettait aux journaux d’illustrer ce qui se passait dans le tribunal, et qui a perduré alors que les photographies étaient interdites.

Les carnets de voyages, annotations du souvenir

Je pense aussi que j’aimais déjà, avant de découvrir cette tendance du Sketching Notes, les carnets de voyage et les bande-dessinées « verbeuses ».

Les carnets de voyage

Les carnets de voyage sont emplis d’annotations, souvent sur des preuves matérielles du voyage collées dans ledit carnet.

page de carnet de voyage illustrée

Illustrations sur un carnet de voyage

Encore plus de magnifiques exemples de dessins sur des carnets de voyage (l’image est bien trop loooongue pour que je l’intègre dans ma page) : http://www.duitang.com/people/mblog/14879816/detail/ (trouvé via le Pinterest de Carnet Voyageur)

Les bande-dessinées « verbeuses »

La BD belge et ses histoires littéraires

Je suis assez friande de…texte dans les bande-dessinées. Non que j’aime les cases avec des bulles plus grandes que la partie illustrée de Blake et Mortimer (Damn,leurs aventures me plaisent, by Jove !) ou d’Alix (aucune sympathie pour ces histoires, en revanche, je n’en ai jamais compris les fans).

page de la BD Blake et Mortimer

Page issue de Blake et Mortimer, avec des bulles très envahissantes

page de la BD Alix

Alix, le texte avant l’image. Autant lire Bécassine.

 

Non, je pense plutôt à des bande-dessinées contenant des annotations supplémentaires. Un peu comme l’Echo des Savanes par exemple. Et j’aime les bande-dessinées qui jouent des annotations et des adressages au lecteur.

Dans les plus connues, selon moi, on retrouve les « Rubriques-à-brac » de Gotlib, ou encore plus connu Chris Ware. Le travail de construction et de narration de Chris Ware est très intéressant, mais voyons quelques exemples de planches.

Gotlib – Rubriques à brac

Page d’une Rubrique à brac sur les vacances d’été

Et le Pélican :

Gotlib, le manuel du pélican

Chris Ware

Source : http://www.nytimes.com/interactive/2014/04/10/books/review/13ware.html

Demi-page de Building Stories, par Chris Ware

On remarque les annotations qui enrichissent l’image principale

 

Source : http://kottke.org/12/07/building-stories-new-chris-ware-graphic-novel

Encore plus vieux…

Dans les bande-dessinées un tout petit peu plus anciennes, je dirais que ce sont les BD de mes parents, on retrouve Robert Crumb et Mandryka (le Concombre masqué).

Robert Crumb

Crumb (le site officiel de R. Crumb)

Admirez la construction graphique de la page

Mandryka

Marc-Antoine Mathieu

Et mon auteur préféré à ce jour, juste devant l’inimitable Gotlib, voici Marc-Antoine Mathieu.

Sa série Julius Corentin d’Acquefacques est vraiment excellente. Si vous connaissez d’autres BD du même genre, ou que vous reliez à cette série, n’hésitez surtout pas à me laisser un commentaire.
Depuis quelques années, je n’ai pas le temps de suivre l’actualité BD, cela me rendra donc un immense service.

Les cases se meuvent et deviennent des pièces

Jeu sur l’espace, les lignes, les cases, les mots

Mise en abyme ou recursion en BD

 

J’espère que mon propos vous paraîtra clair après avoir vu ces images.  L’idée est de dire que la bande-dessinée joue depuis longtemps avec les codes de construction de la page pour y déposer une histoire. Si vous lisez plus de bande-dessinée, avec un œil  attentif, vous pourrez certainement vous améliorer en Sketching Notes.