Asciidoc est certes plus puissant, mais Ô combien moins accessible au non initié.
Rédiger de la doc, c'est déjà difficile de convaincre les gens, et d'arriver à leur faire faire. Si en plus ils doivent se poser des questions existentielles, c'est pas la peine de rêver. Le critère pour espérer avoir de la doc, c'est rendre ça le plus simple possible, tant pis si c'est au détriment des fonctionnalités.
Par contre, j'avoue que le manque de normalisation est un peu pénible. Quand on met du markdown dans une spec API (type OAS ou Swagger), c'est très chiant de jamais savoir comment ça sera rendu au final (sachant que chaque portail API peut interpréter ça légèrement différemment).
# Oui mais...
Posté par Dring . En réponse au lien Les limites de Markdown (pour rédiger de la documentation) face aux capacités d’Asciidoc. Évalué à 7.
Asciidoc est certes plus puissant, mais Ô combien moins accessible au non initié.
Rédiger de la doc, c'est déjà difficile de convaincre les gens, et d'arriver à leur faire faire. Si en plus ils doivent se poser des questions existentielles, c'est pas la peine de rêver. Le critère pour espérer avoir de la doc, c'est rendre ça le plus simple possible, tant pis si c'est au détriment des fonctionnalités.
Par contre, j'avoue que le manque de normalisation est un peu pénible. Quand on met du markdown dans une spec API (type OAS ou Swagger), c'est très chiant de jamais savoir comment ça sera rendu au final (sachant que chaque portail API peut interpréter ça légèrement différemment).