J'ai eu une expérience avec ça la semaine passée. Je vais vous raconter…
Je devais donner une spécification d'API à une grosse boîte via un consultant qui travaille pour notre société et la grosse boîte en question.
Mes docs des APIs, je les rédige en markdown, puis généralement on les convertit en html/css pour les lire plus facilement à l'écran (j'ai mis une belle css).
Évidemment, travailler en markdown permet d'avoir un suivit de version optimal avec git ou autre.
[Je ne suis pas 100% satisfait de markdown pour ma rédaction technique style API, si quelqu'un à des expériences avec un autre format de balisage léger plus adapté qu'il me le fasse savoir :)]
Donc, je génère le tout, j'exporte tant bien que mal mon html en PDF pour que cela reste joli et je fournit la doc.
Le consultant me dit qu'il faut un paragraphe initial qui indique la version et la date dans le document ainsi ce sera une garantie de la version que l'on donne…
J'ajoute un paragraphe avec ces infos un peu "inutiles" puisque le suivit des versions est déjà optimal avec mon DVCS et je renvoie en PDF.
Le consultant me dit que le format ne va pas, qu'il faut du word, comme ça on peut le modifier à plusieurs.
Je lui explique que mon format source n'est pas word et que le plus simple sera de faire du copier coller depuis la version html.
Il prend la version html et part travailler sous word…
Maintenant, voyons les changements si importants qui nécessitaient word: mettre des header/footer avec le logo de notre entreprise, fichier en l'air toute la mise en page (qui contenait des textes dans des styles subtilement différents comme du monospace) pour que ça ressemble plus à des docs que l'on a déjà, casser plusieurs bout de l'API au passage.
Il revient fièrement avec la version word, et me dit sur un ton didactique, voilà maintenant c'est un document qui peut nous servir de référence pour gérer les versions !
Sur ce je lui explique que ma doc de part son format original est synchronisée avec mes API dans un vrai gestionnaire de version et qu'il n'y a aucun risque d'avoir du mal à tracer les changements, que word n'est pas adapté à cela et que les doc techniques ne devraient pas mélanger contenu et formatage.
Après cette explication, il est partit sans rien dire. Les gens ne comprennent pas ce qu'est du markdown, ce qu'est un vrai gestionnaire de version et ce qu'on veut vraiment dire, il continuera comme ses autres collègues à ne jure que par du word et à pester lorsqu'il recevra n'importe quel autre format…
[^] # Re: Partager les sources plutôt que les binaires
Posté par RB . En réponse au journal Un DCVS pour des documents 'binaires' ?. Évalué à 10.
J'ai eu une expérience avec ça la semaine passée. Je vais vous raconter…
Je devais donner une spécification d'API à une grosse boîte via un consultant qui travaille pour notre société et la grosse boîte en question.
Mes docs des APIs, je les rédige en markdown, puis généralement on les convertit en html/css pour les lire plus facilement à l'écran (j'ai mis une belle css).
Évidemment, travailler en markdown permet d'avoir un suivit de version optimal avec git ou autre.
[Je ne suis pas 100% satisfait de markdown pour ma rédaction technique style API, si quelqu'un à des expériences avec un autre format de balisage léger plus adapté qu'il me le fasse savoir :)]
Donc, je génère le tout, j'exporte tant bien que mal mon html en PDF pour que cela reste joli et je fournit la doc.
Le consultant me dit qu'il faut un paragraphe initial qui indique la version et la date dans le document ainsi ce sera une garantie de la version que l'on donne…
J'ajoute un paragraphe avec ces infos un peu "inutiles" puisque le suivit des versions est déjà optimal avec mon DVCS et je renvoie en PDF.
Le consultant me dit que le format ne va pas, qu'il faut du word, comme ça on peut le modifier à plusieurs.
Je lui explique que mon format source n'est pas word et que le plus simple sera de faire du copier coller depuis la version html.
Il prend la version html et part travailler sous word…
Maintenant, voyons les changements si importants qui nécessitaient word: mettre des header/footer avec le logo de notre entreprise, fichier en l'air toute la mise en page (qui contenait des textes dans des styles subtilement différents comme du monospace) pour que ça ressemble plus à des docs que l'on a déjà, casser plusieurs bout de l'API au passage.
Il revient fièrement avec la version word, et me dit sur un ton didactique, voilà maintenant c'est un document qui peut nous servir de référence pour gérer les versions !
Sur ce je lui explique que ma doc de part son format original est synchronisée avec mes API dans un vrai gestionnaire de version et qu'il n'y a aucun risque d'avoir du mal à tracer les changements, que word n'est pas adapté à cela et que les doc techniques ne devraient pas mélanger contenu et formatage.
Après cette explication, il est partit sans rien dire. Les gens ne comprennent pas ce qu'est du markdown, ce qu'est un vrai gestionnaire de version et ce qu'on veut vraiment dire, il continuera comme ses autres collègues à ne jure que par du word et à pester lorsqu'il recevra n'importe quel autre format…