Articles

Publié le

La probité journalistique, qualité moins répandue qu'on ne le croit

Dès les premiers échanges, les remarques de chacun des invités ont tout pour surprendre l’animateur tant elles prennent le contre-pied des « éléments de langage » en usage, à ce moment-là, dans les médias. On explique d’abord que ces bombardements, en effet effroyables, ne concernent pas « la ville d’Alep » mais seulement deux ou trois quartiers de l’est de la cité.

Source : Le courage d’Yves Calvi –
Un autre exemple de la manière dont les médias de masse sont capables de tordre la vérité. Au final on est capable de faire dire tout et son contraire à l’actualité, signe qu’il est plus qu’indispensable de prendre son temps et se documenter sérieusement avant d’affirmer quoi que ce soit.

Publié le

Documenter vos projets autrement avec git et asciidoc

Un collègue m’a fourni une vidéo intéressante sur une manidère différente de gérer une documentation projet : https://youtu.be/1rKgVF5CEEY
Il est vrai que cela fait un moment qu’on tourne autour du pot. Les wikis c’est bien mais le bon logiciel est toujours délicat à trouver. Sans détailler la réflexion ici (peut être une autre fois) il y a toujours une contrainte qui fait que ce n’est jamais parfait…
Je suis donc en train de me pencher sur une mouvance qui me semble intéressante : gérer sa documention as a code. En simplifiant cela veut dire que votre documentation est gérée dans un dépot git, avec un outil de collaboration sympa comme gitlab et  des fichiers sous forme plain text avec une syntaxe simple et lisible comme markdown ou asciidoc (j’ai tendance à préférer le second actuellement).
Cela vous permet d’avoir une documentation où chacun peut collaborer simplement (coucou pull request). De plus, il se trouve que github et gitlab intègrent les syntaxes asciidoc et markdown en natif, vous pouvez donc déjà naviguer dans votre documentation directement sur leur site web.
Le fin du fin sera de générer un site statique joli (avec un moteur de recherche) et si possible une version pdf. C’est là que l’excellent gitbook entre en action.
Enfin, pour mettre la cerise sur le gateau, vous pouvez rebuilder votre site documentaire de manière automatisée avec un job gitlab ci bien senti.
Au passage, pour le job gitlab je me suis construit une image docker gitbook qui m’aide bien.
Cette manière de faire semble s’étendre car même chez owasp on a choisi de construire le nouveau developer guide de cette manière sur github.
Que du bon donc pour l’instant ! A creuser à l’usage.