Ancien adepte de LaTeX, dans le cas d'une documentation technique, aujourd'hui mon choix se porterait plutôt sur reStructuredText ou markdown.
Ce sont des fichiers textes qui suivent quelques conventions de mise en forme simples (comme celles utilisées pour rédiger cette réponse) qui ont le double avantage d'être faciles à écrire dans n'importe quel éditeur capable de produire du texte, et surtout d'être lisibles tel quel sans que le balisage n'entrave réellement la lecture.
Ensuite, avec un outil tel que Pandoc, il est possible de transformer ces bêtes fichiers textes en tout et n'importe quoi (LaTeX, ePub, pages de man, ou même docx pour peu qu'un client en exprime le besoin...).
Ou encore, grâce à Sphinx pour reStructuredText ou MkDocs pour markdown, un simple fichier de configuration permet de générer aisément de très belles pages statiques pouvant être hébergées n'importe où et ainsi rendues accessible aux moteurs de recherches.
Par ailleurs, les fichiers de documentations peuvent être directement versionnés avec le projet et les commandes pour générer et publier la documentation peuvent être intégrées à la compilation et/ou au déploiement.
Autre exemple de la versatilité de cette solution : une plate-forme comme ReadTheDocs utilise des webhooks pour qu'à chaque commit du projet sur un dépôt public comme GitHub ou BitBucket, les docs sont extraites, générées avec Sphinx/MkDocs et directement publiées.
# Documentation technique au format texte ?
Posté par lerouquin . En réponse au message rédaction documentation technique avec LYX. Évalué à 3.
Ancien adepte de LaTeX, dans le cas d'une documentation technique, aujourd'hui mon choix se porterait plutôt sur reStructuredText ou markdown.
Ce sont des fichiers textes qui suivent quelques conventions de mise en forme simples (comme celles utilisées pour rédiger cette réponse) qui ont le double avantage d'être faciles à écrire dans n'importe quel éditeur capable de produire du texte, et surtout d'être lisibles tel quel sans que le balisage n'entrave réellement la lecture.
Ensuite, avec un outil tel que Pandoc, il est possible de transformer ces bêtes fichiers textes en tout et n'importe quoi (LaTeX, ePub, pages de man, ou même docx pour peu qu'un client en exprime le besoin...).
Ou encore, grâce à Sphinx pour reStructuredText ou MkDocs pour markdown, un simple fichier de configuration permet de générer aisément de très belles pages statiques pouvant être hébergées n'importe où et ainsi rendues accessible aux moteurs de recherches.
Par ailleurs, les fichiers de documentations peuvent être directement versionnés avec le projet et les commandes pour générer et publier la documentation peuvent être intégrées à la compilation et/ou au déploiement.
Autre exemple de la versatilité de cette solution : une plate-forme comme ReadTheDocs utilise des webhooks pour qu'à chaque commit du projet sur un dépôt public comme GitHub ou BitBucket, les docs sont extraites, générées avec Sphinx/MkDocs et directement publiées.