#mylife je viens de commencer un nouveau boulot chez La Roue Verte, une entreprise de covoiturage sur Grenoble, qui met à disposition son outil gratuitement pour les particuliers et base son business model sur du SASS avec les entreprises.
Pourquoi je vous raconte ça ? Parce que lorsque l’on commence un nouveau travail, il faut « rentrer dans la base de code », autrement dit, se familiariser avec le produit. J’ai donc eu la proposition suivante : « On a pas de doc, et ça nous embête, or, quel meilleur moyen de rentrer dans le code que de la rédiger ? Si tu es capable de faire la doc sans faute, c’est que tu as compris comment ça marchait ! ».
Un traitement de texte ? C’est quoi ?
Aussitôt dit, aussitôt fait, me voici à devoir documenter une base de données PostgreSQL, le modèle de notre application. Aucune contrainte sur les outils à utiliser, il faut juste que le rendu final soit un PDF. La solution de facilitée aurait été d’ouvrir LibreOffice Writer et de prendre une à une chaque colonnes de chaque tables en la décrivant. Cela peut sembler fastidieux, mais de toute manière, je n’y échapperai pas. Non, ce qui m’ennuyait dans cette solution, c’était le maintien à jour des données. Si la doc aurait été à jour au moment de sa création, il y avait fort à parier que le fichier texte n’allait pas être modifié par les développeurs lorsqu’ils modifieraient le schéma de la base, que ce soit par oubli, par flemme ou par manque de temps. Or, dès que le document n’est potentiellement plus le reflet exact de la base, même si la différence entre les deux est mineure, il ne devient plus possible de s’y référer, on ne peut pas savoir ce qui est correct de ce qui n’est plus à jour. L’intégralité du document (et ma vingtaine d’heures passées à le rédiger) devient inutile. Une doc pas à jour équivaut à « pas de doc ».
La génération automatique à la rescousse
La solution pour avoir une documentation toujours à jour ? La générer directement depuis le schéma de la base de données. Un coup de DuckDuckGo, et je découvre Autodoc, un outil en ligne de commande à qui on donne simplement l’accès à la base de données, et qui nous extrait des fichiers au format HTML, Dot, Dia et DocBook XML. HTML ? Parfait pour moi ça. Facile à mettre en forme en deux coups de CSS, qui se transformera en une seconde en un PDF grâce au « Imprimer dans un fichier » de Firefox… Je lance la génération.
Toutes les tables sont là, les colonnes aussi, mais aussi les contraintes (clef primaire, clef étrangère, not null, valeur par défaut…) ou encore les fonctions triggers, des statistiques, bref, beaucoup de choses. Les graphiques .dot ne sont pas vraiment exploitables, mais pas grave, ce n’est pas ça qui m’intéresse. Après un coup de CSS pour rendre le résultat moins moche, j’ai maintenant une documentation qui se génère en une commande, et qui est donc toujours à jour par rapport au schéma de la base de données.
C’est une bonne nouvelle, mais les informations contenues dans ce HTML sont finalement assez faibles. Il n’y a rien de plus que ce que je pourrais lire dans le create.sql, certes, sous une forme un peu plus lisible, mais tout de même, ce qui est intéressant, c’est de dire à quoi correspondent chaque table et chaque colonne. Ici, je connais leur type et leurs contraintes, et je peux imaginer ce qu’elles font grâce à leur nom, mais tout de même, ce n’est pas cela que l’on appelle une documentation.
COMMENT ON, THE solution
Après quelques recherches supplémentaires, j’ai donc trouvé la solution idéale pour le moment : COMMENT, qui permet d’ajouter très facilement un commentaire à à peu près tout et n’importe quoi (table, column, constraint, index, database… la liste est longue, vous pouvez la consulter dans la doc). La syntaxe est ultra simple :
COMMENT ON TABLE user IS 'Contient les utilisateurs inscrits dans l''application.'; -- Ajoute un commentaire sur la table "user"
COMMENT ON TABLE user.name IS 'Le nom de l''utilisateur'; -- Ajoute un commentaire sur la colonne name de la table "user"
Un coup de génération, et les commentaires s’affichent dans le .html 🙂
Cerise sur le gâteau, postgresql_autodoc nous permet de choisir le template sur lequel il doit se baser pour génerer la doc. J’ai donc modifié ce fichier pour retirer tout ce qui était inutile, améliorer le design et lui demander d’interpreter le HTML dans les commentaires. Magnifique ! Grâce à des <span class="technique"> et un bout de JavaScript, nous voici maintenant capable de masquer ou afficher en un clic les parties techniques de la documentation, celles qu’on a pas besoin de montrer quand on présente la partie métier de l’application.
Bien sûr, cette solution n’évite pas le fait que si un commentaire n’est pas ajouté ou pas mis à jour lors de la modification du schéma, la doc ne sera pas exactement à jour. Mais comme elle se base sur le schéma pour être généré, on est absolument sûr que toutes les tables et colonnes sont là et avec le bon nom, ce qui est déjà nettement mieux qu’une doc non reliée à la base de données.
Voilà, la mauvaise nouvelle, c’est que la commande COMMENT est spécifique à PostgreSQL et n’est pas dans le standard SQL, mais de toute manière, Postgres est la meilleure DB non ?
Je n’ai pas l’habitude de reprendre du contenu d’autres sites web dans mes propres articles. D’ailleurs, je reste fidèle à ce principe, puisque je ne vais pas le faire ici. Pour autant, ce billet a comme premier objectif de vous renvoyer vers celui de klaire que je viens de découvrir :
J’ai trouvé cette infographie très claire et bien réalisée, je vous encourage donc à la découvrir et à la partager comme je viens de le faire. Elle est pour moi un support idéal pour résumé l’ampleur de l’histoire à un public pas forcément touché par ce genre de révélations.
Allez, c’est votre devoir maison, faîtes-le, maintenant ! Présentez ce document à des gens autour de vous et faîtes les réfléchir sur le sujet !
… C’est bon, c’est fait ?
Bon. Alors, vous avez probablement eu deux types de réactions différentes après la lecture de l’infographie :
Réaction possible numéro une : « Moi, j’m’en fous, j’ai rien à cacher, rien à me reprocher, ils s’en foutent la NSA que je bouffe du fast food et que mon père soit charpentier. »
Voici comment je réagis à ce genre d’affirmation (n’hésitez pas à partager dans les commentaires comment vous réagissez vous, ça m’intéresse ! On peut sûrement peaufiner notre discours pour qu’il soit le plus convainquant possible) :
- Le problème de l’État lui même : En théorie, l’État oeuvre pour le bien des citoyens. En réalité, on voit bien que c’est pas toujours le cas. Et surtout, même s’il prend soin des citoyens en ce moment même, on ne sait pas de quoi le futur sera fait, et laisser 50 ans de données à la nouvelle dictature du futur n’est pas quelque chose qui m’enchante. (Imaginez vous un instant si un dictateur avec des idées d’éradication arrivait au pouvoir maintenant que Facebook est là, avec tout ce que vous avez pu y publier depuis des années…)
- Le problème des entreprises qui nous embauchent : On dit ce qu’on veut sur le respect de la vie privée, clairement, les recruteurs et même les RH une fois dans l’entreprise surveillent ce que vous dîtes sur les réseaux sociaux. Et dans la période de chômage actuelle, les entreprises peuvent se permettre de faire les difficiles sur les gens qu’elles embauchent, ce qui est loin d’être le cas pour les personnes cherchant du travail…
- Le problème des entreprises dont nous sommes les clients : c’est pour moi clairement le plus gros problème, pourtant, nous n’entendons généralement que les deux premiers quand on parle de vie privée. C’est le plus gros car c’est celui qui nous impacte le plus souvent, le plus facilement. Prenons un exemple simple, vous voulez assurer votre moto. Vous êtes un garçon, de 24 ans, avec le permis depuis 4 mois. Rien qu’avec ces trois critères (age, sexe, durée de permis), nous voyons une différence de tarif du simple au double avec par exemple une femme de 40 ans ayant le permis depuis 15 ans. Juste parce que, statistiquement, vous avez plus de chance d’avoir un accident. Alors imaginez maintenant que, statistiquement, il se révèle que les gens aimant les fast food et ayant un père charpentier ont deux fois plus d’accident que les autres (c’est un exemple, je n’ai rien contre les charpentiers, bien au contraire). Que va faire votre assurance, à votre avis ? Doubler le prix. Voici quelque chose qui implique votre vie en ligne, ou vous n’avez « rien à cacher », et qui impact pourtant directement votre vie réelle, hors ligne, votre portefeuille. J’ai beaucoup de choses à dire sur ce sujet, et il fera donc l’objet d’un autre article, mais j’espère vous avoir déjà mis la puce à l’oreille.
Réaction possible numéro deux : « OMG OMG OMG c’est horrible qu’est-ce que je peux faire ? »
J’ai déjà donné quelques pistes dans mon précédent article lors des révélations sur PRISM. Je ne vais pas m’étendre sur le sujet une fois de plus, l’objet de ce billet était surtout de vous faire découvrir l’infographie de @klaire. En résumé : utilisez des logiciels Libres (Firefox, pas Internet Explorer ni Chrome, si vous avez un geek sous la main, demandez lui de vous installer Linux), éviter les services des entreprises américaines (prism-break.org résume bien les alternatives existantes), protéger son surf (installer les extensions httpseverywhere et ghostery (ou disconnect.me) dans firefox, activer do not track et désactiver les cookies tiers dans firefox…). Je m’étendrai certainement plus sur ce dernier point dans un prochain billet. En attendant, diffusez l’infographie, le monde doit savoir !
English version below.
Pour rappel, on désigne par « fédération » l’échange des données entre les différentes instances de diaspora* (appelées pods). Il s’agit donc du protocole qui permet aux serveurs de communiquer entre eux.
Avec le travail en cours pour extraire le code s’occupant de la fédération du reste du code de diaspora (oui, ce code devrait devenir une gem à part et donc être utilisable par n’importe quel projet qui veut parler avec diaspora* !), il me semble qu’un petit article de vulgarisation sur la fédération n’est pas de trop. J’ai régulièrement des remarques sur différents points qui m’obligent à réexpliquer un peu comment tout ça marche, alors un joli article à la limite du technique mais compréhensible par tous, ça me semble la solution parfaite, je n’aurai plus qu’à donner ce petit lien… 😀
Alors, comment les serveurs de diaspora* communiquent-ils, pour réussir à faire qu’être inscrit sur n’importe lequel d’entre eux permet (presque) la même chose que si tout le monde était sur le même serveur ? (comment ça, presque, je vous entends dire ? Oui, il y a quelques cas où vous n’aurez pas le même résultat après avoir effectué la même action quand vous êtes sur deux pods différents. Ce billet a justement comme but de vous expliquer pourquoi). Read More
OpenStreetMap, la carte coopérative libre
iPhoto est un logiciel de gestion d’images de la suite iLife produit par Apple. La société a annoncé le remplacement de Google Map par OpenStreetMap pour les cartes utilisées par ce logiciel.
Les responsables d’OpenStreetMap s’en félicitent, puisque cela prouve que le projet, né en 2004, a maintenant atteint un niveau de maturité suffisant pour intéresser jusqu’aux plus grandes sociétés.
Pour rappel, le but du projet OpenStreetMap est de mettre à disposition de tous une carte du monde entièrement libre (sous licence CC BY-SA). Le projet est collaboratif, tout le monde est donc invité à participer à sa création, avec comme résultat des cartes beaucoup plus détaillées que celles proposées par Google la majorité du temps. (SebSauvage avait d’ailleurs fait un article sur une comparaison des cartes disponibles sur le web il y a peu).
Et comme c’est Apple, il fallait s’y attendre, il y a déjà embrouille sur la licence, ce qui est relativement incroyable au vu de celle-ci : » Vous êtes libre de copier, distribuer, transmettre et adapter nos cartes et données, à condition que vous créditiez OpenStreetMap et ses contributeurs ». L’unique obligation n’est pour l’instant pas respectée, hormis une mention « powered by OSM »
Il faut aussi noter que l’application se base pour le moment sur des cartes de 2010, qui ne sont donc pas à jour. Nul doute que cela sera rapidement corrigé cependant.
Concernant la rivalité avec Google, il est intéressant de lire le billet de Frederik Ramm, contributeur de longue date à OSM, tant au niveau du code que des données, et co-auteur d’un livre sur le sujet (traduction disponible ici).
Dans ce billet, intitulé « Google n’est pas l’ennemi », Frederik Ramm explique que bien que la majorité des gens voient OSM comme un rival à Google Map, ce qui n’est pas forcément vrai. Il cite quelques exemples où la coopération était de mise, et affirme « Chez OpenStreetMap, nous ne cherchons pas à être une alternative à Google Maps, mais bien plutôt aux bases de géodonnées administratives ou produites commercialement. Nous sommes plutôt des concurrents pour TeleAtlas ou Navteq que pour Google. Google avait aussi commencé à récolter ses propres géodonnées dans sa jeunesse, mais seulement parce qu’ils souffrent du même problème qu’OpenStreetMap, à savoir le manque de géodonnées disponibles à des conditions acceptables. »
Un point de vue qui vient de l’intérieur même d’OSM et qui s’oppose à l’idée générale que l’on a des deux services, que l’on ne peut s’empêcher de voir en concurrent.
Voici en tout cas une nouvelle qui apporte à nouveau un bel exemple d’un projet libre qui vient se placer tout en haut de l’échelle et côtoie les plus grands.