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 ?

 

Publicités

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.

#nppt Pour avoir plusieurs profils Firefox

Quand on fait du dév, qu’on ne peut pas upgrader Firefox (je travaille avec Firefox 16, plaignez moi,c’est bon maintenant, ça va mieux) et qu’on a besoin de tester, le mieux, c’est de faire des profils différents. Chaque profil bénéficie de ses extensions, c’est fort pratique. Et parfois un peu pénible : par exemple, quand on a bien installé une extension mais qu’on cherche à l’avoir sur un autre profil, et qu’on ne se souvient plus du nom de l’extension, on veut changer de profil.

Mais comment retrouver ses profils ?

– Who you gonna call ?
– ProfileSwitcher :: Modules pour Firefox.

Compte-rendu du PHP Tour lyonnais [23-24 juin 2014]

On l’avait bien attendu, ce PHP Tour, puisque je me souviens être allée à Paris seule défendre le dossier, il y a 3 ans. A l’époque, le dossier n’était pas celui attendu et nous avions dû revoir notre copie.
Depuis, j’ai relâché mes responsabilités au sein de l’AFUP pour me concentrer sur d’autres activités (comme la Game Dev Party, par exemple).
Pour ce PHP Tour, ce qui était amusant pour moi, a été de retrouver tous les « copains » de l’AFUP. Après avoir longtemps été du côté de l’organisation, j’avoue que j’ai savouré ma participation en tant que conférencière.

Banniere PHP Tour 2014 j'y serai, sponsor argent eZ Publish

La veille du PHP Tour avait lieu le repas pour les conférenciers, et par un micmac dans ma mémoire défaillante (c’est pourquoi je note tout tout tout), j’ai pensé que ce repas était le soir du premier jour. Heureusement qu’un tweet de Benoît Lévèque m’a remémoré la date…au dernier moment.

J’ai donc cessé ce que j’étais en train de faire, et suis partie dîner avec les autres conférenciers. Ce soir là, la pression atmosphérique était énorme et la chaleur écrasante. Je suis partie tellement à la hâte que j’ai gardé ma « robe du dimanche », et je ne le regrette pas car elle était bien aérée !

Le dîner fût excellent et la compagnie fort agréable. J’ignore si c’était la chaleur ou le vin, mais j’ai eu l’impression que les conférenciers étaient assez excités d’être à Lyon pour le PHP Tour.

Le lendemain, je revêtais ma tenue « corporate », et, parée de mon joli polo orange eZ Systems, je regagnai la Manufacture des Tabacs. Sur place, j’étais la première parmi mes collègues…qui m’avaient demandé de venir en avance pour leur donner un coup de main ! Après avoir attendu un moment mes collègues farceurs, j’ai visité les lieux. J’ai profité d’un peu de café et de viennoiseries, avant de consulter nonchalamment le programme. C’est alors que je me suis rendue compte que j’avais décalé le repas conférencier dans mon esprit mais également le reste du PHP Tour ! Je pensais faire ma conférence le second jour, et en fait c’était le premier.

Du coup, j’ai passé la journée en étant assez stressée et en tâchant, toutefois, de faire bon accueil aux visiteurs de notre stand. Et malgré mon passif en présentation orale, j’avais énormément d’appréhension avant mon passage. A tel point que je n’ai pas eu le coeur à aller écouter mes pairs, incapable de me concentrer sur ce qu’ils racontaient. J’ai assisté à la Keynote de Rasmus Lerdorf, qui a insisté sur le Faire, et agire pour changer. Sa keynote complétait parfaitement le Mix IT.

Le midi, nous avons pu emprunter le superbe stand Microsoft Azure pour présenter la nouvelle interface Admin.

L’après-midi s’est écoulé entre répétitions et chronométrage de ma conférence, réponses aux questions sur le stand, discussions plus ou moins « business » avec les ex-collègues présents.

Ensuite, vint le moment de ma présentation « Pourquoi la documentation compte ? ». J’étais dans une des petites salles, en fin de journée, avec ma conférence sur la Documentation. Nous étions peu dans ce sauna mais les auditeurs étaient attentifs et valeureux.

Assez tendue au départ, une fois lancée, j’étais concentrée sur les messages et notions que je voulais faire passer, entre retour d’expérience et conseils pour avoir une meilleure documentation. J’avais gardé sous le coude quelques sujets que je n’avais pas abordé dans ma conférence, et au final, les questions ont permis de finir en beauté.
Je décerne la palme  de la question à :

« Va-t-on faire du DDD ? Documentation Driven Development ? »

Ma réponse a été que parfois, si le Product Owner est très très détaillé dans ses Stories, on peut arriver à de la DDD. J’ai par exemple eu la chance de travailler avec @samuel_v2 qui fait partie de ces PO qui décrivent le comportement attendu et écrivent quasiment une documentation par Story pour obtenir ce qu’il pense être le mieux pour le logiciel.

IMG_9595_MD

La soirée sur la péniche au Red House s’est déroulée sans moi, obligations familiales oblige. Et le lendemain matin, un peu moins fraîche que la veille, je regagnai notre stand à la moquette orange pour accueillir les visiteurs, après un shoot de carburant, tout de même.

Cette seconde journée a été plus agréable pour moi, le stress étant retombé. Je me suis offert des tee-shirts « Last Night PHP Saved My Life ». J’ai pu aller écouter quelques conférences sur le Monitoring et la Dette Technique. J’y ai découvert des outils, et des idées. Puis j’ai été attentive aux Lightning Talks, qui sont toujours un exercice amusant à regarder. Le périmètre doit être extrêmement limité de manière à ce que l’auditoire profite des 5 minutes allouées.

Mes collègues, Bertrand Dunogier et André Romcke ont fait un Lightning Talk sur le cache d’eZ Publish Platform. Le sujet est passionnant, riche et le format LT ne permet pas forcément de faire comprendre à un public débutant en eZ Publish les subtilités et les forces du cache.

Cependant, j’espère que vous aurez l’occasion d’en savoir plus sur le sujet lors d’un prochain événement. En attendant, il y a la doc !

Installation de ReadtheDocs en local (Ubuntu)

Je suis les instructions sur ma Ubuntu fraîchement installée : https://read-the-docs.readthedocs.org/en/latest/install.html

Premièrement j’installe python. Avec apt-get install, tout simplement. Je fais confiance à mon OS.
Comme l’installation bloque, je finis par installer un paquet de versions de Python mais les paquets se débrouillent pour me faire un :
python 2.7 et un python3

sudo apt-get install python-virtualenv virtualenvwrapper
sudo apt-get install python3-pippython

Quand j’arrive à la partie d’installation avec pip, premièrement c’est Mercurial qui me claque à la figure. Alors, je lance la commande avec pip3 au lieu de pip tout court.

cd readthedocs.org
pip3 install -r pip_requirements.txt

Erreur

Downloading/unpacking virtualenv==1.11.1 (from -r pip_requirements.txt (line 2))
Real name of requirement virtualenv is virtualenv
Error while getting https://pypi.python.org/packages/source/v/virtualenv/virtualenv-1.11.1.tar.gz#md5=7875c2d8c2075571abe5e727449af4d8 (from https://pypi.python.org/simple/virtualenv/)
Exception:
Traceback (most recent call last):
File "/usr/lib/python3.3/urllib/request.py", line 1252, in do_open
h.request(req.get_method(), req.selector, req.data, headers)
File "/usr/lib/python3.3/http/client.py", line 1061, in request
self._send_request(method, url, body, headers)
File "/usr/lib/python3.3/http/client.py", line 1099, in _send_request
self.endheaders(body)
File "/usr/lib/python3.3/http/client.py", line 1057, in endheaders
self._send_output(message_body)
File "/usr/lib/python3.3/http/client.py", line 902, in _send_output
self.send(msg)
File "/usr/lib/python3.3/http/client.py", line 840, in send
self.connect()
File "/usr/lib/python3/dist-packages/pip/download.py", line 90, in connect
sock = socket.create_connection((self.host, self.port), **self.connection_kwargs)
File "/usr/lib/python3.3/socket.py", line 417, in create_connection
for res in getaddrinfo(host, port, 0, SOCK_STREAM):
FileNotFoundError: [Errno 2] No such file or directory

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File "/usr/lib/python3/dist-packages/pip/basecommand.py", line 139, in main
status = self.run(options, args)
File "/usr/lib/python3/dist-packages/pip/commands/install.py", line 266, in run
requirement_set.prepare_files(finder, force_root_egg_info=self.bundle, bundle=self.bundle)
File "/usr/lib/python3/dist-packages/pip/req.py", line 1033, in prepare_files
self.unpack_url(url, location, self.is_download)
File "/usr/lib/python3/dist-packages/pip/req.py", line 1161, in unpack_url
retval = unpack_http_url(link, location, self.download_cache, self.download_dir)
File "/usr/lib/python3/dist-packages/pip/download.py", line 534, in unpack_http_url
resp = _get_response_from_url(target_url, link)
File "/usr/lib/python3/dist-packages/pip/download.py", line 569, in _get_response_from_url
resp = urlopen(target_url)
File "/usr/lib/python3/dist-packages/pip/download.py", line 143, in __call__
response = self.get_opener(scheme=scheme).open(url)
File "/usr/lib/python3.3/urllib/request.py", line 473, in open
response = self._open(req, data)
File "/usr/lib/python3.3/urllib/request.py", line 491, in _open
'_open', req)
File "/usr/lib/python3.3/urllib/request.py", line 451, in _call_chain
result = func(*args)
File "/usr/lib/python3/dist-packages/pip/download.py", line 123, in https_open
return self.do_open(self.specialized_conn_class, req)
File "/usr/lib/python3.3/urllib/request.py", line 1255, in do_open
raise URLError(err)
urllib.error.URLError:

Version de virtualenv
Je mets donc à jour virtualenv

sudo apt-get upgrade python-virtualenv

Cela ne fait rien de plus 😦
Alors je cherche sur Internet et je finis par trouver un moyen de mettre à jour virtualenv pour python 2.7

python2.7 -m easy_install virtualenv

La suite…j’ai répété la procédure d’installation et tout s’est bien passé. C’est presque décevant !